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

Плохие программисты…

•Увиливают от составления всякой документации

•Не следят за своевременным обнов% лением документации

•Считают, что «если мне было трудно это написать, то пусть другие пому% чаются, пытаясь в этом разобраться»

См. также

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

Выбор правильных имен – мощное средство создания самодокумен% тируемого кода.

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

Если приходится писать комментарии, то нужно делать это пра% вильно.

Глава 19. Спецификации

Код должен быть самодокументируемым, но по многим причинам все же нужны отдельные спецификации.

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

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

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

1.Группировка взаимосвязанного кода делает эти связи более замет% ными. Как можно осуществить это группирование? Какие методы документируют эти связи наиболее заметным образом?

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

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

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

5.Если код действительно самодокументируемый, какой объем до% полнительной информации необходим?

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

7.Эту простую C%функцию пузырьковой сортировки можно усовер% шенствовать. Что именно в ней нехорошо? Напишите улучшенный, самодокументируемый вариант.

void bsrt(int a[], int n)

{

for (int i = 0; i < n 1; i++) for (int j = n 1; j > i; j )

if (a[j 1] > a[j])

{

int tmp	= a[j 1];
a[j 1]	= a[j];
a[j]	= tmp;

}

}

8.Работа со средствами документирования кода обнаруживает ряд ин% тересных проблем. Выскажите свое мнение по следующим вопросам:

a.Следует ли при проверке документации проверять также и код, сравнивая с комментариями в файлах исходного кода, или про# верять спецификации, сравнивая со сгенерированной докумен% тацией?

b.Где следует документировать протоколы и прочие не относящие% ся к API вопросы?

c.Документируете ли вы закрытые/внутренние функции? Если это код 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
111Click										m
w									o
	w
w								.c
	.
		p					g
			df			n		e
				-x cha

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

9.Если вы работаете с кодом, в котором отсутствует грамотная доку% ментация, и вам необходимо внести изменения или добавить новые методы или функции, что правильнее – снабдить их грамотными комментариями или оставить недокументированными?

10. Можно ли написать самодокументируемый код на языке ассемблера?

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

1.Какой из встречавшихся вам код был лучше всего документиро% ван? В чем были его особенности?

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

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

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

3.Каким образом вы выделили важные фрагменты в последнем коде, который писали? Постарались ли вы сделать малозаметной закры% тую информацию?

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

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