hang		e
			C				E
		X
	-							d
	F								t
	D								i
									r
P						NOW!			o
					BUY
				to
w Click								126m
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
Глава 5. Заметки на поляхClick										m
w									o
	w
w								.c
	.
		p					g
			df			n		e
				-x cha

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

Файлы README

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

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

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

Работа с комментариями

Комментариями удобно пользоваться при написании кода. Но не зло% употребляйте ими.

Помощь при написании программ

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

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

комментарии. Оцените их в соответствии с обсуждавшимися здесь критериями и отредактируйте или удалите. Не двигайтесь дальше без проведения такой ревизии.

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

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

Заметки об исправлении ошибок

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

//<ссылка на баг> заменено на метод blah.foo2()

//поскольку blah.foo() некорректно обрабатывал

//<некоторое условие>

blah.foo2();

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

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

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

Устаревание комментариев

Комментарии разрушаются. Любой плохо сопровождаемый код подвер% жен разрушению; в нем появляются неприглядные заплаты и теряется

				hang		e
			C				E
		X
	-							d
	F								t
	D								i
									r
P						NOW!			o
					BUY
				to
w Click								128m
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
Глава 5. Заметки на поляхClick										m
w									o
	w
w								.c
	.
		p					g
			df			n		e
				-x cha

Случай из жизни

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

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

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

Если вы изменили код, проверьте правильность комментариев, находящихся рядом с ним.

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

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

Сопровождение и бессодержательные комментарии

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