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

бом эти данные. Можно потом подтвердить их, послав по электрон% ной почте.

b.Если вопрос уже разъяснен в документации, ткните спрашивающе% го носом в это место со словами RTFM.1

Глава 5. Заметки на полях

Вопросы для размышления

1.Как могут различаться необходимость в комментариях и их содержа ние в следующих типах кода:

a.Язык ассемблера низкого уровня (машинный код)

b.Сценарии командного интерпретатора

c.Однофайловая среда тестирования

d.Крупный проект C/C++

Язык ассемблера наименее выразителен и дает меньше всего средств для написания самодокументируемого кода. Вследствие этого в коде ассемблера требуется больше всего комментариев, причем на гораздо более низком уровне, чем в других языках – в комментариях кода на ассемблере обычно разъясняется и «почему», и «как».

Особой разницы между тремя оставшимися вариантами нет. Сценарии командного интерпретатора (shell scripts) бывают достаточно трудны для чтения; в этом отношении они представляют собой прото%Perl. По% лезно писать подробные комментарии. В большой программе на C/C++ предпочтительным может оказаться грамотное программирование.

2.Есть инструменты для подсчета процента строк комментариев в ис ходном тексте. Насколько они полезны? Насколько точно могут они оценить качество комментариев?

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

3.Если вам встретился непонятный код, как лучше внести в него некото рую ясность – добавив комментарии с вашим пониманием его работы или переименовав переменные/функции/типы, дав им более содержа тельные имена? Какой подход может оказаться проще? Какой подход будет безопаснее?

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

1Read The (…) Manual.

				hang		e
			C				E
		X
	-							d
	F								t
	D								i
									r
P						NOW!			o
					BUY
				to
w Click								606m
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
Ответы и обсуждениеClick										m
w									o
	w
w								.c
	.
		p					g
			df			n		e
				-x cha

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

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

4.Если вы написали блок комментариев к C/C++ API, куда его лучше по местить – в заголовочный файл, где объявляется функция, или в файл, где находится ее реализация? В чем преимущества и недостатки каж дого из расположений?

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

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

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

Конечно, в Java и C# есть только один файл с исходным кодом; обыч% но используются комментарии в формате Javadoc или C# XML.

Вопросы личного характера

1.Рассмотрите внимательно файлы исходного кода, над которыми рабо тали в последнее время. Прочтите свои комментарии. Так ли они хоро ши, если быть честным? (Ручаюсь, что при чтении кода вам захочется сделать несколько изменений!)

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

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

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