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

Глава 2. Тонкий расчет

Система структурирования и расположения кода влияет на распо% ложение комментариев.

Глава 3. Что в имени тебе моем?

Один из аспектов самодокументируемого кода: правильный выбор имен.

Глава 4. Литературоведение

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

Глава 18. Защита исходного кода

Системы управления версиями хранят историю файлов, поэтому не стоит излагать ее в комментариях.

Контрольные вопросы

Подробное обсуждение этих вопросов можно найти в разделе «Ответы и обсуждение» на стр. 605.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

a.Чьи комментарии лучше других? Почему? Чьи самые плохие? Есть ли корреляция между качеством их комментариев и каче% ством кода в целом?

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

4.Включаете ли вы в исходные файлы историю их модификации? Ес% ли да:

a.Поддерживаете ли вы ее вручную? Зачем, если система управле% ния версиями может автоматически делать это вместо вас? На% сколько точно ведется история?

b.Разумна ли такая практика в действительности? Как часто воз% никает потребность в таких данных? Каковы преимущества хра% нения их в исходном файле по сравнению с иным механизмом?

5.Добавляете ли вы свои инициалы или помечаете каким%то иным способом свои комментарии, которые делаете в чужом коде? Указы% ваете ли вы дату комментирования? Когда и зачем вы это делаете – полезна ли такая практика? Сослужили ли вам когда%либо пользу

чьи%то инициалы или отметка о дате?

				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