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

Адвокат дьявола

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

Ускоренные процедуры (см. раздел «Методологии ускоренной разработки» на стр. 547) уделяют значительно меньше внимания составлению спецификаций, но они не поощряют писать код как бог на душу положит. Поскольку спецификации не пишутся са% ми по себе, легко устаревают и требуют сопровождения, а у про% граммистов и без того работы хватает, разумно писать только са% мые необходимые документы. Нужно всегда избегать долгих про% цедурных барьеров. Но любую спецификацию, от которой вы от# казались, нужно заменить равноценным объемом информации. Не пренебрегайте спецификациями, если вы не заменили их до% кументами равного качества, содержащими ту же информацию.

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

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

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

Что должны содержать спецификации?

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

Корректность

Несмотря на очевидность, это крайне важное требование. Некор% ректная спецификация может стать причиной многих дней напрас%

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

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

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

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

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

Понятность

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

Как и хороший код, лучшие спецификации пишутся с точки зре% ния читателя, а не писателя. Информация представляется так, что% бы быть понятной новичку, а не в удобном для автора виде. Блез Паскаль как%то извинялся: «Это письмо получилось у меня слиш% ком долгим, потому что у меня не было времени его укоротить». Для хорошего стиля характерны краткость и очевидность главного смысла, не затененного многословием. Для этого требуются лиш% ние время и труд, но оно того стоит, если в результате достигается простота изложения.

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

Полнота

Спецификация должна быть самодостаточной и полной. Это не озна% чает, что в ней должна содержаться вся мыслимая информация;

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

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

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

Проверяемость

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

Модифицируемость

Ничто не должно устанавливаться навечно – ни код, ни документы. Если спецификация требует обновления (например, для исправле% ния фактической ошибки), это не должно вызывать затруднений. Жесткая спецификация помогает вам обрести почву под ногами. Но если спецификация неверна, в этом нет никакого смысла. Доку% мент должен быть доступен для редактирования (т. е. должен быть обеспечен доступ к источнику, а не просто экземпляру в формате PDF), а процедура выпуска и обновления не должна быть слишком обременительной.

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

Самоописательность

В каждой спецификации должны присутствовать как минимум следующие части:

•Форзац, ясно показывающий название документа, подзаголо% вок, авторов, номер версии, дату последней модификации и ста% тус доступа (например, закрытый документ компании, распро% странение на условиях NDA, открытый доступ).

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

•Термины и определения, необходимые для понимания содержи% мого. (Но не относитесь к читателю свысока: если документ предназначен инженерам%программистам, не нужно объяснять им, что такое RAM.)

•Ссылки на аналогичные или цитируемые документы.

•Исторический раздел, перечисляющий важные модификации и версии.

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

Прослеживаемость

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

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

Составляя спецификацию, обдумайте ее содержание. Выберите структуру и словарь, понятные аудитории, и убедитесь, что документ корректен, по& лон и содержит собственное описание.

Процесс составления спецификаций

То, что написано без усилий, обычно читается без удовольствия.

Сэмюэл Джонсон

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

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

2.Напишите документ. Действительно, это трудная часть. Что пи% сать, зависит от типа спецификации.

3.Организуйте обсуждение документа. Привлеките всех, кому он мо% жет быть интересен.

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

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

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

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

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

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

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

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

•Автора нужно подбирать правильно. Служба маркетинга не напи% шет вам функциональные спецификации; она снабжает вас требо% ваниями. Менеджеры не проектируют код; это делает разработчик, у которого есть соответствующие знания и умение. Автор должен уметь писать – это мастерство, которым можно овладеть, мускул, требующий упражнений.

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

Вот несколько советов по написанию документа:

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

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

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

•Завершив разработку спецификации, не забывайте про нее. Она

должна работать и своевременно обновляться. Функциональная

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

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

Языковые барьеры

Ненавижу определения.

Бенжамин Дизраэли

Очень внимательно пишите текст спецификации. По сравнению с кодом английский язык полон двусмысленностей и сложностей. По газетным заголовкам особенно хорошо видно, насколько неод% нозначными бывают простые английские предложения: «Stolen painting found by tree», «Kids make nutritious snacks», «Red tape holds up new bridge» и «Hospitals are sued by 7 foot doctors».

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

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

Must (Должен)

Слово must (или shall, или is required to) означает, что сле% дующее определение является безусловным требованием спе% цификации.

Must not (Не должен)

Слова must not (или shall not) означают безусловное запреще% ние спецификации.

Should (Следует)

Пользуйтесь should (или recommended, рекомендуется) для обозначения необязательного требования – поведения, кото% рое можно игнорировать, но только если понятны и учтены все возможные последствия.