hang		e
			C				E
		X
	-							d
	F								t
	D								i
									r
P						NOW!			o
					BUY
				to
w Click								Практическиеm		методологии самодокументирования
w
	w								o
	.							.c
		p					g
			df			n		e
				-xcha

				hang		e
			C				E
		X
	-							d
	F								t
	D								i
									r
P						NOW!			o
					BUY
				to
103Click										m
w									o
	w
w								.c
	.
		p					g
			df			n		e
				-x cha

Самосовершенствование

Как научиться более успешно писать самодокументируемый код? Обратимся снова к процессу написания книг и посмотрим, не найдется ли там чего%нибудь полезного.

Есть простое правило совершенствования писательского мастер% ства: больше читайте, и вы станете писать лучше. Критиче% ское чтение работ признанных мастеров помогает понять, какие приемы хороши, а какие нет. При этом вы добавляете в свой ар% сенал новые приемы и идиомы.

Точно так же, читая большие объемы кода, вы совершенствуетесь как программист. После чтения достаточного количества хороше% го кода запах скверного кода начинает чувствоваться за версту. Сотрудники таможни просматривают ежедневно такое количест% во паспортов, что при виде поддельного паспорта у них мгновен% но срабатывает чутье. Даже тщательные подделки не проходят мимо их глаз. Точно так же плохой код бросается в глаза, когда вырабатывается чутье на его отличительные признаки.

Имея такой опыт, вы естественным образом станете применять хорошую практику в собственном коде. Вы сами начнете заме% чать, что написали плохой код, и потому будете испытывать не% приятное чувство.

вы приложили все усилия, чтобы написать понятный код, все осталь% ное нужно снабдить комментариями. Чтобы код было легко понять, его нужно дополнить уместным объемом комментариев. Каким именно?

Помещайте в код комментарии только в том случае, если не удается облег& чить его понимание иными способами.

Сначала попробуйте воспользоваться другими приемами. Например, проверьте, нельзя ли сделать код понятнее, изменив имя или создав вспомогательную функцию, и таким образом избежать комментиро% вания.

Практические методологии самодокументирования

В завершение этой главы мы сравним два конкретных метода докумен% тирования кода. Помните, что эти методы менее предпочтительны, чем те, которые мы уже рассмотрели. Как сказано у Кернигана и Плоэра, «нужно не документировать плохой код, а переписать его заново». (Kernighan Plaugher 78)

				hang		e
			C				E
		X
	-							d
	F								t
	D								i
									r
P						NOW!			o
					BUY
				to
w Click								104m
w
	w								o
	.							.c
		p					g
			df			n		e
				-xcha

Грамотное программирование

				hang		e
			C				E
		X
	-							d
	F								t
	D								i
									r
P						NOW!			o
					BUY
				to
Глава 4. ЛитературоведениеClick										m
w									o
	w
w								.c
	.
		p					g
			df			n		e
				-x cha

Грамотное, или литературное, программирование (literate program# ming) – это экстремальная технология самодокументируемого кода, предложенная знаменитым специалистом в вычислительной технике Дональдом Кнутом. Он написал книгу под этим названием, в которой и описал эту технологию (Knuth 92). Это радикальная альтернатива традиционной модели программирования, хотя некоторые считают, что период грамотного программирования был крупной неудачей в карьере Д. Кнута. Но даже если не принимать эту технологию за единственно верное и правильное учение, кое%что полезное из нее можно извлечь.

Лежащая в основе идея проста: нужно писать не программу, а доку% мент. Язык документации тесно привязан к языку программирова% ния. Ваш документ в основном описывает то, что программируется, но при этом допускает компиляцию в нужную программу. Таким обра% зом, исходный код – это документация, и наоборот.

Грамотную программу пишут почти как рассказ, который легко или даже интересно читать человеку. На нее не накладываются порядок и ограничения, требуемые синтаксическим анализатором. Но это не следует воспринимать как язык, в котором комментарии поставлены с ног на голову: скорее это поставленный с ног на голову метод про% граммирования. Грамотное программирование представляет собой особый образ мышления.

Первоначально Кнут соединил TEX (язык разметки для набора доку% ментов) с C и создал систему под названием WEB. Инструментарий грамотного программирования анализирует файл программы и гене% рирует либо форматированную документацию, либо исходный код, который можно обработать традиционным компилятором.

Конечно, это еще один вид технологии программирования, как струк% турное программирование или объектно%ориентированное программи% рование. Качество документации при этом не гарантируется. Оно, как обычно, зависит от программиста. Однако в грамотном программиро% вании акцент смещается на создание описания программы, а не на соз% дание кода, который ее реализует.

По%настоящему достоинства грамотного программирования проявля% ются на этапе сопровождения продукта. Наличие документации хоро% шего качества и достаточного объема значительно облегчает сопрово% ждение исходного кода.

У грамотного программирования много полезных качеств:

•Грамотное программирование делает упор на написание документа% ции.

•Оно заставляет взглянуть на код с другой стороны, поскольку в про%

цессе работы необходимо писать объяснения и обоснования.

				hang		e
			C				E
		X
	-							d
	F								t
	D								i
									r
P						NOW!			o
					BUY
				to
w Click								Практическиеm		методологии самодокументирования
w
	w								o
	.							.c
		p					g
			df			n		e
				-xcha

				hang		e
			C				E
		X
	-							d
	F								t
	D								i
									r
P						NOW!			o
					BUY
				to
105Click										m
w									o
	w
w								.c
	.
		p					g
			df			n		e
				-x cha

•При внесении изменений в код появляется больше шансов, что про% изойдет соответствующее обновление документации, поскольку од% но и другое удобно располагается рядом.

•Обеспечивается наличие всего лишь одного документа для всего объема кода. Всегда присутствует версия документации, соответст% вующая коду, с которым вы работаете; это и есть сам код.

•Грамотное программирование способствует включению в докумен% тацию элементов, обычно отсутствующих в комментариях. Напри% мер: описание применяемых алгоритмов, доказательства коррект% ности, обоснование проектных решений.

Тем не менее грамотное программирование не панацея. У него есть ряд серьезных недостатков:

•Программы по этой технологии труднее писать, поскольку боль% шинству программистов она кажется неестественной. Мы не склон% ны рассматривать код как печатный документ, который необходи% мо форматировать. Более привычно мысленно моделировать пото% ки управления и взаимодействующие объекты.

•Возникает необходимость в дополнительных этапах компиляции, что замедляет разработку программ. Хорошей инструментальной поддержки пока не существует.

Обрабатывать грамотные программы весьма тяжело, поскольку компилятору необходимо извлечь все фрагменты программы и со% брать их в правильном порядке. Очень удобно, что документ можно писать в любом порядке, но в C к коду предъявляются определен% ные требования, например директивы #include должны находиться в начале. В результате на практике приходится прибегать к некото% рым компромиссам.

•В некоторых случаях документируется код, для которого это совсем не требуется. Случаи, когда не документируется большой объем простого кода, также часто встречаются. Тогда это уже нельзя на% звать хорошей грамотной программой, и вся затея не имеет смысла.

Если описывается буквально все, то в этом шуме можно пропустить важные куски документации.

•Кнут рассматривал программиста как литератора. Но есть много программистов, которые не напишут рассказа под страхом смерти, хотя пишут прекрасный код. Возможно, они представляют собой исключение, но не каждый хороший программист может проявить способности к грамотному программированию.

•Тесная привязка документации к коду может составить проблему. Например, вы фиксируете окончательную версию своего кода, не разрешая вносить изменения, но документация требует доработки.

Изменить документацию – значит, изменить исходный код. В ре% зультате появляется окончательная версия исполняемого кода и окончательная версия документации к тому же коду, которые

				hang		e
			C				E
		X
	-							d
	F								t
	D								i
									r
P						NOW!			o
					BUY
				to
w Click								106m
w
	w								o
	.							.c
		p					g
			df			n		e
				-xcha

				hang		e
			C				E
		X
	-							d
	F								t
	D								i
									r
P						NOW!			o
					BUY
				to
Глава 4. ЛитературоведениеClick										m
w									o
	w
w								.c
	.
		p					g
			df			n		e
				-x cha

нужно связать вместе, что представляет собой административную проблему.

В одной из последующих глав обсуждаются спецификации программ% ного обеспечения. Как грамотное программирование относится к спе% цификациям? Грамотная программа не может заменить функциональ% ную спецификацию с описанием работы, которую нужно сделать. Од% нако должна существовать возможность разработать грамотную про% грамму по такой спецификации. Грамотная программа на практике скорее представляет собой комбинацию обычного кода со специфика% цией проектирования и реализации.

Инструментарий документирования

Существует целый вид программных средств, занимающих промежу% точное положение между технологией грамотного программирования и созданием внешних спецификаций. Эти инструменты генерируют документацию из исходного кода, вытаскивая из него блоки особым образом форматированных комментариев. Особенно модной такая тех% ника стала после того, как Sun ввела Javadoc в качестве базовой ком% поненты платформы Java. Вся документация Java API генерируется с помощью Javadoc.

Чтобы лучше разобраться в том, как это работает, рассмотрим пример. Формат комментариев может немного отличаться, но в принципе до% кументирование класса Widget осуществляется так:

/**

*Это документация класса Widget.

*Программа определяет начало комментария

*с помощью особой последовательности '/**' .

*@author Имя автора

*@version Номер версии

*/

class Widget

{

public:

/** * Здесь документируется метод. */

void method();

};

Средство документирования анализирует все файлы вашего проекта, извлекает документацию, строит перекрестную базу данных всей из% влеченной информации и выводит милый документ со всей этой ин% формацией.

Документировать можно практически любой код, который вы пишете: классы, типы, функции, параметры, флаги, переменные, пространства

				hang		e
			C				E
		X
	-							d
	F								t
	D								i
									r
P						NOW!			o
					BUY
				to
w Click								Практическиеm		методологии самодокументирования
w
	w								o
	.							.c
		p					g
			df			n		e
				-xcha

				hang		e
			C				E
		X
	-							d
	F								t
	D								i
									r
P						NOW!			o
					BUY
				to
107Click										m
w									o
	w
w								.c
	.
		p					g
			df			n		e
				-x cha

имен, пакеты и т. д. Есть средства для получения многообразных дан% ных, которые позволяют:

•Задать информацию об авторских правах

•Зафиксировать дату создания

•Получить информацию о перекрестных ссылках

•Пометить код как устаревший

•Дать синопсис для краткой справки

•Описать все параметры функции

Существует много средств документирования – как свободно распро% страняемых, так и коммерческих. Мы уже упомянули Javadoc; други% ми популярными инструментами являются NDoc для C# и превосход% ное средство Doxygen (www.doxygen.org).

Это отличный метод документирования, позволяющий комментиро% вать код с разумной степенью детализации и не составлять при этом отдельной спецификации. Кроме того, документацию можно читать прямо в файле исходного кода, что бывает очень удобно.

Средства документирования имеют много достоинств:

•Как и грамотное программирование, этот подход поощряет состав% ление документации и поддержание ее актуальности.

•Не требуется дополнительного шага для получения кода, допуска% ющего компиляцию.

•Технология более естественна и не требует значительных измене% ний или долгого изучения. Поскольку код позволяет генерировать документ, не требуется искусственно делать код похожим на книгу или решать утомительные задачи структурирования текста.

•Средства документирования поддерживают богатые возможности поиска, перекрестных ссылок и выделения кода.

Следует, однако, учитывать последствия подхода к документирова% нию, основанного на комментариях:

•В отличие от грамотного программирования он имеет практиче% скую ценность только для документирования API, но не внутренне% го кода. На уровне операторов нужно пользоваться обычными ком% ментариями.

•Взглянув на файл исходного кода, трудно получить представление о его содержимом, поскольку оно испещрено бесчисленными ком% ментариями, связанными с документированием. Приходится поль% зоваться обзорными функциями, предоставляемыми средством до% кументирования. Результат может быть красиво отформатирован, но это может доставить неудобства при работе в редакторе кода.

Пользуйтесь инструментарием грамотного документирования для автома& тической генерации документации по вашему коду.