Основы Extreme Programming: документация
Original text at www.xprogramming.com
"Outside of a dog, a book is man's best friend. Inside of a dog, it's too dark to read." --Groucho Marx
("Вычтем собаку, и лучшим другом человека окажется книга. Впрочем, в собаке много не вычитаешь - слишком темно". Гручо Маркс)
Вне ХР-проекта вам, скорее всего, понадобится документация, и конечно же, ее нужно написать. Однако внутри проекта вы будете иметь столько вербальных коммуникаций, что едва ли вам понадобится что-либо еще. Доверяйте себе, и почувствуйте разницу.
Методология ХР была разработана таким образом, чтобы везде, где только можно, непосредственная коммуникация между людьми заменяла собой письменную документацию. Устное общение протекает намного быстрее и является куда более эффективным способом передачи информации, нежели обмен документацией. Если собрать участников проекта вместе, то понадобится гораздо меньше бумажной волокиты.
Документирование требований
ХР в "чистом виде" предполагает, что ваш клиент (который принимает бизнес-решения; знает, что именно ему нужно; может расставить приоритеты в работе) находится в непосредственной близости от разработчиков ("on site"). Можно спорить, насколько реально заполучить такого клиента, однако это никак не меняет тот факт, что если вы находитесь в одной комнате с командой разработчиков, вам не приходится писать им бесконечные памятки и служебные записки.
Как считается в ХР, лучше всего ставить задачи перед программистами, устраивая совместное обсуждение. Мы уже не раз рассказывали, что во время работы над С3 проектом в таких дискуссиях, как правило, использовались различные документы: таблицы, выдержки из технических требований, которые генерируются вне проекта и т.д. По этому поводу в книге Extreme Programming Installed можно найти следующее:
Требования пользователя (User Stories) состоят из двух компонентов. Первый - карточка с записями. Мы советуем записывать на ней всего несколько предложений а также указывать, где можно найти дополнительную документацию по этому поводу. Второй и наиболее важный компонент - это ряд обсуждений, которые должны пройти между заказчиком и разработчиками за время жизни этого конкретного требования. Все эти обсуждения должны быть отражены в дополнительной документации, прилагаемой к карточке; их стоит "проигрывать" во время CRC-сессий и, что еще лучше, учитывать в приемочных тестах и в коде программы. (Курсив автора)Как видите, самое главное здесь то, что требования документируются в гораздо более полной и информативной форме, нежели обычное письменное требование к системе - они имеют форму автоматизированных тестов, с помощью которых контролируется результаты использования программного продукта.
В данном случае, чтобы соотносить свою работу с требованиями заказчика, мы комбинируем устную коммуникацию и автоматические тесты. В результате команде практически не нужны традиционно задокументированные требования.
В некоторых проектах иногда приходится обсуждать требования вне команды разработчиков. Эти ситуации в методологии ХР не описаны. Нельзя сказать, что мы против этого...просто мы не уделяли этому особого внимания. Ну, разве что вот:
Если возникает необходимость в каком-либо документе, то заказчица должна затребовать его точно так же, как и любое другое свойство программы: с помощью карточки. Команда оценит стоимость разработки такого документа, а заказчица определит, в какой итерации она хотела бы его получить.Документирование дизайна системы
Как и большинство других инкрементных разработок (начиная с Спирального Метода Боэма), ХР не синтезирует дизайн системы, а скорее, постепенно наращивает его в процессе работы. Опять-таки, поскольку в ХР все программисты активно общаются между собой, им не приходится помногу работать с бумажной документацией. Весь проект создается на основе двухнедельных итераций, так что на реализацию того или иного свойства уходит не более нескольких дней (это происходит потому, что свойства разбиваются на малые составляющие, которые и реализуются одна за другой, а вовсе не потому что ХР-программисты круче обычных).
В ХР-окружении обычные артефакты проектирования, как правило, недолговечны. Команда может собраться, порисовать на доске или в блокноте UML-диаграммы, а затем сразу же приступить к разработке того свойства программы, которое она только что обсудила.
Нередко ХР-команды прикрепляют листочки с дизайном системы на стенку. Там они и болтаются довольно долго, причем больше в качестве украшения, чем действительно нужного документа. Лично я очень редко видел, чтобы люди хоть раз разглядывали эти картинки. Скорее уж, они будут задавать друг другу вопросы или сядут программировать в паре с тем человеком, который знает на них ответ. Интересно, почему разработчики поступают именно так, а не обращаются к картиночкам? Я думаю, просто потому, что общение и парное программирование лучше для этого подходят. Впрочем, доказательств у меня нет - только личный опыт.
ХР-шники говорят, что если команде нужен какой бы то ни было документ (будь то рисунок, таблица или просто набор слов), она должна создать его. Однако если вы создаете документ, а потом не используете, то может быть, это намек на то, что он вам все-таки был совсем не нужен.
Это справедливо и по отношению ко внутренней документации. Если вам нужно обсудить дизайн с человеком, с которым невозможно пообщаться лично, значит пришло время сесть за написание соотвествующего документа. Это очевидно, а кто же будет отрицать очевидное? В конце концов, мы экстремалы, а не тупицы.
Когда же приходит время сдавать работу и передавать готовый программный продукт службе поддержки или пользователям (а может быть, и другой группе разработчиков, которые используют вашу систему для того, чтобы создать на ее основе что-то новое), то конечно, вы должны сопроводить свой продукт соответствующей документацией. Что касается пользователей, то для них нужно написать обычный набор справочных материалов. Для программистов из службы поддержки мы предложили бы написать короткий документ, в котором будет описана архитектура системы или ее метафора (возможно, с несколькими UML-диаграммами), основные понятия, наиболее важные классы, и т.д. Нам кажется, что это будет достаточным введением в систему, неким высокоуровневым предметным указателем, если хотите.
Документирование программного кода
Средоточие методологии ХР - инкрементные разработки. Весь цикл работ должен начинаться с Простого Дизайна, обсуждаться в процессе Парного Программирования, поддерживаться при помощи всесторонних Блочных Тестов и развиваться за счет Рефакторинга.
Однако чтобы эта комбинация работала, нужно иметь возможность заниматься рефакторингом программного кода: код должен быть максимально прозрачным и понятным. Существуют правила, которые помогают программисту писать простой код (поищите где-нибудь их обсуждения с точки зрения повторного использования кода). Говоря коротко, если во время написания программного кода у вас в голове есть какая-то идея, то вы должны сделать так, чтобы она была отражена в нем четко и недвусмысленно.
Если код требует комментариев, говорят, что он "воняет", то есть, что его надо улучшить, так как он недостаточно понятен сам по себе. Во первых, нужно попытаться изменить код так, чтобы он стал как можно более ясным. Комментировать же надо только то, что никаким образом не удается упростить.
Блочные тесты тоже представляют собой документацию. Они показывают, как создавать объекты, как их использовать, и что эти объекты будут делать. Как и в случае с приемочными тестами, принадлежащими заказчику, у блочных тестов есть одно очень важное преимущество перед любой другой документацией: все они выполнимые. Эти тесты не рассказывают о ваших представлениях по поводу работы кода - они реально отражают то, что код делает на самом деле.
Как правило, самой команде разработчиков достаточно документации в виде программного кода. В другом окружении (как и в описанных выше случаях) вам может понадобиться дополнительная документация. Например, это может произойти в ситуации, когда код должен быть передан каким-то другим разработчикам. В таком случае, разумеется, она должна быть написана.
Руководство пользователя
Лучше всего будет, если технические писатели начнут работать рядом с программистами, как часть команды. Более подробно (и в более вольном стиле) эта идея изложена в заметке Extreme Programming и руководство пользователя.
Другая документация
Поскольку ХР изначально разрабатывалась как минимальная методология, мы не следуем RUP'у (мы не отрицаем его почтенности, просто идем другим путем) и не составляем длинный список всех документов "на всякий случай", из которого вы впоследствии будете выбирать наиболее подходящие для вашего конкретного проекта. Вместо этого ХР старается максимально сблизить всех участников проекта, сделать так, чтобы они работали в атмосфере быстрого реагирования, доверить им самим решать, что именно им нужно для успешной работы (не обязательно документация, это может быть любая форма расширения и совершенствования проекта).
Некоторые считают, что наш путь слишком рискованный, что команде "нельзя доверять" самой решать, что ей нужно для работы. Мы же на своем опыте убедились, что те команды, которые работают с установкой на быструю обратную связь с заказчиком, быстро понимают что к чему, и прекрасно справляются со своими задачами.
Заключение
Кажется, я коснулся всех областей применения документации. Думаю, читателю стало ясно, что мы очень хотим минимизировать объемы документации. При этом, как и все разумные люди, мы хотим, чтобы проект имел всю необходимую документацию. Но не более того. Может быть, наши взгяды и покажутся в чем-то нетрадиционными. Это связано с тем, что мы верим в способность разработчиков (при условии близкого и непосредственного общения как между собой, так и с заказчиком) решать, что им нужно. Именно поэтому мы и минимизируем процесс - включая документацию - вместо того, чтобы накапливать бесполезные вещи "на всякий случай".