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

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

Учитесь писать ровно столько комментариев, сколько необходимо. Отдайте предпочтение качеству, а не количеству.

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

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

Не пожалейте труда, чтобы ваш код не требовал поддержки в виде уймы ком& ментариев.

Чем меньше комментариев, тем реже встретятся плохие комментарии.

Что помещать в комментарии?

Прежде чем станешь писать, научись порядочно мыслить!

Гораций

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

Описывайте «почему», а не «как»

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

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

писан четко и ясно, правда? Вместо этого опишите, почему код напи% сан так, а не иначе, или какую задачу решает нижеследующий блок операторов.

Постоянно следите за тем, как писать: /* обновить структуру WidgetList из GlbWLRegistry */ или /* сохранить сведения о виджете на будущее */.

Комментируя одно и то же, во втором варианте вы излагаете смысл ко% да, а в первом просто описываете его действие.

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

Хорошие комментарии объясняют «почему», а не «как».

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

Не нужно описывать код

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

Один источник для каждого факта. Не копируйте код в комментариях.

Не подменяйте код

Если вы видите комментарий, сообщающий что%то, что может быть выражено средствами самого языка (например, // доступ к этой пере менной должен осуществляться только из класса foo), попытайтесь выра% зить это синтаксическим способом.

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

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

•Не пишите комментарии, описывающие смысл переменной, – луч%

ше дайте ей подходящее имя. Комментарий, который вы собира%

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

лись написать, часто и подскажет, каким должно быть имя этой пе% ременной!

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

•Не следует преждевременно оптимизировать (и тем самым делать менее понятным) свой код.

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

Как сделать комментарии полезными

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

Документировать необычное

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

С другой стороны, незачем комментировать очевидное. Помните: не копируйте код в комментариях!

Говорить правду

Когда комментарий комментарием не является? Когда он лжет. Пусть вы никогда умышленно не пишете лжи, но очень легко слу% чайно допустить искажение истины, особенно при модификации уже прокомментированного кода. Вносимые в код изменения легко могут сделать комментарии неточными. Раздел «Работа с коммен% тариями» на стр. 126 описывает тактику борьбы с этим явлением.

Быть стоящими

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

Быть понятными

Ваш комментарий должен служить аннотацией и объяснением ко% да. Избегайте двусмысленности. Будьте как можно более конкрет% ны (не нужно писать диссертацию по каждой строчке). Если кто%то,

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

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

Быть вразумительными

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

Думайте, что пишете в комментариях; не давите бездумно на клавиши. Прочтите комментарий снова в контексте кода. Ту ли информацию он со& держит?

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

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

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

Не отвлекаться

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

Описание былого

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

Ненужный код

Не нужно удалять код путем заключения его в комментарии. Это приводит к путанице. Даже при отладке в пожарном режиме (без штанов, без отладчика и без printfs), не прячьте код, помещая его в блок комментариев. Воспользуйтесь директивами C #ifdef 0 . . .

#endif или аналогичными. Такие конструкции допускают вложен% ность, и их назначение более понятно (что особенно важно, если по% том вы забудете сделать приборку).