hang		e
			C				E
		X
	-							d
	F								t
	D								i
									r
P						NOW!			o
					BUY
				to
w Click								Главаm		19. Спецификации
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
671Click										m
w									o
	w
w								.c
	.
		p					g
			df			n		e
				-x cha

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

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

3. На каких машинах хранится ваш исходный код?

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

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

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

1. Что лучше – плохая спецификация или ее полное отсутствие?

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

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

Если спецификация слишком многословна и скрывает информацию, тогда, возможно, лучше (в конечном счете) переписать ее.

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

2. Насколько детальной должна быть хорошая спецификация?

Ответ: достаточно детальной, где значение «достаточно» зависит от проекта, команды, содержимого, качества сопутствующих докумен% тов и фазы луны. Лишние детали определенно могут мешать; ясно, что

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

при определенном уровне детализации спецификация превращается просто в код. Однако неясности в ключевых областях могут привести к катастрофическим последствиям.

3.Нужно ли требовать, чтобы все документы в компании/проекте были выдержаны в одинаковом стиле?

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

В конечном счете, важнее содержимое ваших документов, а не их вид.

4.Как нужно хранить документы? Например, стоит ли создавать для них указатель (по типу или проекту)?

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

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

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

Следует хранить документы, соблюдая какую%то форму контроля вер% сий, и следить за соответствием версий документов и версий кода. Это входит в стратегию управления конфигурацией (см. раздел «Управле% ние конфигурацией» на стр. 456).

5. Как организовать рецензирование спецификации?

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

Альтернативой является виртуальное рецензирование путем опроса по электронной почте или рассылки печатных экземпляров и изуче% ния пометок рецензентов.

				hang		e
			C				E
		X
	-							d
	F								t
	D								i
									r
P						NOW!			o
					BUY
				to
w Click								Главаm		19. Спецификации
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
673Click										m
w									o
	w
w								.c
	.
		p					g
			df			n		e
				-x cha

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

•Качество содержания. (Полнота, корректность и т. д.? Это имеет первостепенное значение.)

•Качество стиля представления. (Соответствует ли документ прави% лам проекта?)

•Качество стиля текста. (Пишет ли автор не хуже Шекспира или как пятилетний ребенок? В программных спецификациях плохо и то, и другое!)

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

6.Делает ли самодокументирование кода ненужными все специфика ции? А какие либо отдельные типы?

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

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

7. Как можно организовать работу над документом нескольких авторов?

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

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

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

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

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

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

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

1. Кто решает, что должно содержаться в ваших документах?

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

2.Рассмотрим ваш текущий проект. Есть ли у вас для него:

a.Спецификация требований

b.Архитектурная спецификация

c.Проектная спецификация

d.Функциональная спецификация

e.Какая нибудь еще спецификация

Являются ли они актуальными? Являются ли они полными? Знаете ли вы, где находятся самые свежие версии? Есть ли у вас доступ к ста рым версиям?

Если какие%то из них у вас отсутствуют или их качество неудовлетво% рительно, то почему? Как можно исправить положение?

Кому поручено следить за актуальностью документов? Поддержка версий документов – важный аспект создания спецификаций; про% верьте наличие ясного плана ее осуществления.

3.Есть ли у вас контроль версий ваших документов? Если да, то как он организован?

Известно несколько технологий управления версиями документов:

•Хранить их в системе контроля исходного кода.

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

•Воспользоваться файловой системой: ввести номер версии в имя файла, содержащего документ (можно хранить архив старых вер%

сий в отдельном каталоге).