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
w Click										m
w
	w								o
	.							.c
		p					g
			df			n		e
				-x cha

4

Литературоведение

Техника написания самодокументируемого кода

В этой главе:

•Как документировать код

•Грамотное

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

•Средства

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

По#настоящему серьезное отношение к писательскому делу – одно из двух непременных условий.

Второе, к сожалению, – талант.

Эрнест Хемингуэй

Современная сборная мебель (в плоской упа% ковке) – большое достижение, перед кото% рым даже у опытного столяра возникает чувство смущения и благоговения. Как пра% вило, она толково спроектирована и в конце концов превращается именно в то, что вам было нужно.

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

				hang		e
			C				E
		X
	-							d
	F								t
	D								i
									r
P						NOW!			o
					BUY
				to
w Click								94m
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

Жаль, что теперь не делают такие вещи, как раньше.

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

Хорошим кодом может быть только хорошо документированный код. Мы пишем код для того, чтобы изложить четкий набор инструкций – не только для компьютера, но и для тех несчастных, кому потом при% дется исправлять или расширять эти инструкции. На практике код никогда не пишут так, чтобы потом навсегда про него забыть. На про% тяжении всего цикла жизни программного продукта код модифициру% ется, развивается и сопровождается. Для этого необходима инструк% ция, руководство пользователя – документация.

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

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

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

•Нежелательно делать лишнюю работу. Составление документации отнимает много времени, и чтение ее – тоже. Программисты пред% почли бы потратить это время на программирование.

•Все отдельные документы должны быть синхронизированы с любы% ми изменениями в коде. В большом проекте обеспечить это очень трудно. Альтернатива, которую обычно выбирают (не обновлять никакой документации), приводит к появлению опасно неточной и ошибочной информации.

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

чтение соответствующей версии документации.

				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
95Click										m
w									o
	w
w								.c
	.
		p					g
			df			n		e
				-x cha

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

Не пишите код, который нуждается во внешней документации. Он ненаде& жен. Пишите такой код, который понятен без посторонней документации.

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

Как избежать этой напасти? С помощью самодокументируемого кода.

Самодокументируемый код

Идея звучит заманчиво. Но что такое «самодокументируемый» код? Следующая программа является самодокументируемой:

10 PRINT "Я очень маленькая и очень глупая"

20 GOTO 10

Гордиться тут, собственно, нечем. Сложная и имеющая практическую ценность программа требует большого мастерства. Практика показы% вает, что читать компьютерные программы гораздо сложнее, чем пи% сать их. Всякий, кто знаком с Perl, это подтвердит: данный язык пред% ставлялся как предельный случай «напиши и забудь». И вправду, ста% рый код Perl может казаться совершенно непостижимым. Однако не% понятный код можно написать на любом языке, и особых стараний для этого не требуется.

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

Следовательно, вы должны приложить все усилия, чтобы сделать эту документацию хорошей – такой, которую сможет читать каждый. Де% ло в том, что автор кода не единственный человек, которому необходи% мо в нем разбираться. Языки программирования служат для нас сред% ством общения. Общение должно быть понятным. Благодаря ясности кода его качество растет, поскольку ошибки становятся менее вероят% ными (они оказываются более заметными), а сопровождение кода об% ходится дешевле – меньше времени требуется на его изучение.

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

				hang		e
			C				E
		X
	-							d
	F								t
	D								i
									r
P						NOW!			o
					BUY
				to
w Click								96m
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

Не судите о книге по переплету…

Файл с самодокументируемым кодом читается почти как хоро% ший справочник. У него четкая структура, разделы, формат. Его легко читать с первой страницы и до конца, но можно открыть для справки в любом месте. Вот таким и должен быть наш код. Рассмотрим его по частям.

Введение

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

Оглавление

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

Разделы

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

Однако следует учитывать, что размещать в одном файле слишком много программных объектов не следует. Лучше все% го, когда одному классу соответствует один файл. В крупных файлах, решающих много задач, трудно разбираться и очень сложно перемещаться по коду. (Если, следуя этому совету, вы получите слишком много файлов исходного кода, вам необхо% димо поработать над структурой кода более высокого уровня.)

Главы

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

				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
97Click										m
w									o
	w
w								.c
	.
		p					g
			df			n		e
				-x cha

Абзацы

Внутри каждой функции операторы объединяются в блоки. Начальные объявления переменных составляют один логиче% ский блок, отделенный от последующего кода пустой строкой (по крайней мере, так делалось в старом коде C). Это не имеет отношения к синтаксису, а просто облегчает чтение кода.

Фразы

Фразы обычно соответствуют отдельным операторам кода.

Перекрестные ссылки и предметный указатель

Они также не входят в разметку файла исходного кода, но хо% роший редактор или IDE предоставляют возможности пере% крестных ссылок. Научитесь пользоваться ими.

Это любопытная аналогия, но какое отношение она имеет к напи% санию кода? На самом деле многие полезные правила написания книг оказываются ценными и для написания хорошего кода. Ос% войте их, и ваш код будет легче читать. Разбейте код на секции, главы и абзацы. Применяйте форматирование для подчеркива% ния логической структуры кода. Пользуйтесь простыми коротки% ми операторами – как и короткие предложения, их легче читать.

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

Вот пример простой функции, которую никак не назвать самодоку% ментируемой. Что, по вашему мнению, она выполняет?

int fval(int i)

{

int ret=2;

for (int n1=1, n2=1, i2=i 3; i2>=0; i2)

{

n1=n2; n2=ret; ret=n2+n1;

}

return (i<2) ? 1 : ret;

}

Это вполне реальный пример; бесчисленное количество строк готового кода выглядит примерно так же, принося мучения читающим их про% граммистам. Напротив, следующий ниже код является самодокумен% тируемым. Можно по первой же строке определить, какую задачу он решает.

int fibonacci(int position)

{

if (position < 2)