Последнее время я слышу множество разговоров о разработке, основанной на тестировании (TDD), о разработке, основанной на функционировании (BDD), об экстремальном программировании (XP), о SCRUM-е, о собраниях стоя и ещё Бог знает о каком количестве методик для создания ПО, но все эти методики не имеют смысла, если ПО, которое мы создаём не соответствует требованиям пользователей. Давайте я попробую это объяснить по-другому. Идеальная реализация неправильно составленной спецификации бесполезна. Так же, как и полезность прекрасно написанной библиотеки стремится к нулю, если у неё нет документации. Что-то определённо не так, если ваше приложение не решает поставленную проблему или, если никто не знает как им воспользоваться.
Здорово. И как же нам решить эту проблему? Проще, чем вы думаете, и достаточно важно, чтобы выделить ответ в отдельный параграф.
Первым делом создайте Readme файл.
Именно так — первым делом. Т.е., ещё до того, как вы начнете писать код или тесты или функционирование или пользовательские истории или что угодно ещё. Знаю, знаю, мы разработчики, а не, чёрт возьми, технические писатели! Но вот тут то вы и заблуждаетесь. Написание Readme — это неотъемлемая часть написания хорошей программы. Пока вы не сможете изложить свою мысль в письменном виде, вы всё равно не сможете начать писать код. Что-то было потеряно между Великим Крестовым Походом Против Водопадного Типа Процесса Разработки и Всеобщим Признанием Гибких Методологий Разработки. Не поймите меня превратно: водопадный тип процесса разработки чересчур уж перегибает палку. Большие системы, описанные до мелких деталей, заканчивают своё существование неправильными системами, описанными до мелких деталей. Мы были правы, когда решили пойти против этого. Но то, что заняло место водопадного типа процесса разработки, другая крайность. Теперь мы сталкиваемся с проектами с минимумом плохо написанной документации или вообще с её отсутствием. У некоторых проектов нет даже Readme файла!
Это не приемлемо. Должна быть золотая середина между грудами бумаг технической спецификации и её отсутствием, как таковой. И на самом деле она есть. Эта золотая середина — незаметный и скромный Readme файл.
Важно различать разработку основанную на Readme от разработки основанной на документировании (DDD). Методику разработки основанной на Readme можно, в принципе, рассматривать, как подкласс или неполную версию разработки основанной на документировании. Ограничивая вашу документацию о дизайне до всего одного файла, которому предназначается так же быть и файлом знакомящим другого человека с вашей программой, методика разработки основанная на Readme предохраняет вас от водопадного синдрома в который может превратиться методология разработки основанной на документировании, наказывая вас за слишком длинную или пресыщенную деталями спецификацию, и в то же время, награждая вас поддержанием библиотек небольшими и модульными. Эти нехитрые правила пройдут весь путь вместе с вашим проектом, ведя его в правильном направлении, но без излишних процессов, направленных на контроль того, что вы делаете всё как надо.
Начиная с написания Readme файла в самом начале, вы создаёте для себя ряд существенных преимуществ:
Считайте процесс написания Readme файла для вашего проекта истинным актом творения. Это именно то место, где должны быть выражены все ваши гениальные идеи. Этот документ должен занимать отдельное место, как свидетельство ваших творческих способностей и самовыражения. Readme файл должен быть самым важным документом в вашей базе кода; и это правильно создать его самым первым.
Примечания:
Здорово. И как же нам решить эту проблему? Проще, чем вы думаете, и достаточно важно, чтобы выделить ответ в отдельный параграф.
Первым делом создайте Readme файл.
Именно так — первым делом. Т.е., ещё до того, как вы начнете писать код или тесты или функционирование или пользовательские истории или что угодно ещё. Знаю, знаю, мы разработчики, а не, чёрт возьми, технические писатели! Но вот тут то вы и заблуждаетесь. Написание Readme — это неотъемлемая часть написания хорошей программы. Пока вы не сможете изложить свою мысль в письменном виде, вы всё равно не сможете начать писать код. Что-то было потеряно между Великим Крестовым Походом Против Водопадного Типа Процесса Разработки и Всеобщим Признанием Гибких Методологий Разработки. Не поймите меня превратно: водопадный тип процесса разработки чересчур уж перегибает палку. Большие системы, описанные до мелких деталей, заканчивают своё существование неправильными системами, описанными до мелких деталей. Мы были правы, когда решили пойти против этого. Но то, что заняло место водопадного типа процесса разработки, другая крайность. Теперь мы сталкиваемся с проектами с минимумом плохо написанной документации или вообще с её отсутствием. У некоторых проектов нет даже Readme файла!
Это не приемлемо. Должна быть золотая середина между грудами бумаг технической спецификации и её отсутствием, как таковой. И на самом деле она есть. Эта золотая середина — незаметный и скромный Readme файл.
Важно различать разработку основанную на Readme от разработки основанной на документировании (DDD). Методику разработки основанной на Readme можно, в принципе, рассматривать, как подкласс или неполную версию разработки основанной на документировании. Ограничивая вашу документацию о дизайне до всего одного файла, которому предназначается так же быть и файлом знакомящим другого человека с вашей программой, методика разработки основанная на Readme предохраняет вас от водопадного синдрома в который может превратиться методология разработки основанной на документировании, наказывая вас за слишком длинную или пресыщенную деталями спецификацию, и в то же время, награждая вас поддержанием библиотек небольшими и модульными. Эти нехитрые правила пройдут весь путь вместе с вашим проектом, ведя его в правильном направлении, но без излишних процессов, направленных на контроль того, что вы делаете всё как надо.
Начиная с написания Readme файла в самом начале, вы создаёте для себя ряд существенных преимуществ:
- Самое важное, что вы даёте себе возможность обдумать проект, без необходимости менять код каждый раз, когда вам приходит на ум что-то сделать по-другому или, например, выбрать что же будет в Public API. Помните то ощущение, когда вы впервые начали писать автоматизированные тесты для кода, и осознали, что вы поймали все возможные типы ошибок, которые, в противном случае, могли бы прокрасться в вашу базу кода? Вот это же самое ощущение вы испытаете, если напишите Readme файл для вашего проект до того, как приступите непосредственно к написанию кода.
- А ещё, у вас сразу под рукой будет замечательная документация, как побочный продукт написания Readme файла для того, чтобы определить то, что вы хотите реализовать. И вы увидите, что писать этот документ гораздо легче и приятнее, когда вы только-только приступили к проекту и ваше возбуждение и мотивация находятся на максимуме. Писать же Readme задним числом чертовски скучно и вы точно упустите какие-то важные детали, если так поступите.
- Вы получите даже ещё больше пользы от вашего Readme файла, если вы работаете в команде. Если все в команде имеют доступ к этой информации до того, как вы закончили писать свой код, они могут с уверенностью начинать работу над своими проектами, которые будут взаимодействовать с вашим кодом. Иначе, если интерфейс взаимодействия не определён, вам придётся или писать код последовательно, или же столкнуться с возможностью переписывания большой части кода.
- Гораздо проще вести обсуждение основываясь на чём-то записанном. Если ничего не описано, можно бесконечно обсуждать проблему круг за кругом повторяя одно и то же. Такое простое действие, как запись предложенного решения, означает, что у всех есть конкретная идея, которая может быть оспорена и повторена впоследствии.
Считайте процесс написания Readme файла для вашего проекта истинным актом творения. Это именно то место, где должны быть выражены все ваши гениальные идеи. Этот документ должен занимать отдельное место, как свидетельство ваших творческих способностей и самовыражения. Readme файл должен быть самым важным документом в вашей базе кода; и это правильно создать его самым первым.
Примечания:
- Переводы названий техник разработки программного обеспечения взяты отсюда.
- О принципах разработки через документирование рассказывается в выступлении Corey Oordt на PyCon 2011
