Разработка основанная на Readme

Original author: Tom Preston-Werner
  • Translation
Последнее время я слышу множество разговоров о разработке, основанной на тестировании (TDD), о разработке, основанной на функционировании (BDD), об экстремальном программировании (XP), о SCRUM-е, о собраниях стоя и ещё Бог знает о каком количестве методик для создания ПО, но все эти методики не имеют смысла, если ПО, которое мы создаём не соответствует требованиям пользователей. Давайте я попробую это объяснить по-другому. Идеальная реализация неправильно составленной спецификации бесполезна. Так же, как и полезность прекрасно написанной библиотеки стремится к нулю, если у неё нет документации. Что-то определённо не так, если ваше приложение не решает поставленную проблему или, если никто не знает как им воспользоваться.

Здорово. И как же нам решить эту проблему? Проще, чем вы думаете, и достаточно важно, чтобы выделить ответ в отдельный параграф.

Первым делом создайте Readme файл.

Именно так — первым делом. Т.е., ещё до того, как вы начнете писать код или тесты или функционирование или пользовательские истории или что угодно ещё. Знаю, знаю, мы разработчики, а не, чёрт возьми, технические писатели! Но вот тут то вы и заблуждаетесь. Написание Readme — это неотъемлемая часть написания хорошей программы. Пока вы не сможете изложить свою мысль в письменном виде, вы всё равно не сможете начать писать код. Что-то было потеряно между Великим Крестовым Походом Против Водопадного Типа Процесса Разработки и Всеобщим Признанием Гибких Методологий Разработки. Не поймите меня превратно: водопадный тип процесса разработки чересчур уж перегибает палку. Большие системы, описанные до мелких деталей, заканчивают своё существование неправильными системами, описанными до мелких деталей. Мы были правы, когда решили пойти против этого. Но то, что заняло место водопадного типа процесса разработки, другая крайность. Теперь мы сталкиваемся с проектами с минимумом плохо написанной документации или вообще с её отсутствием. У некоторых проектов нет даже Readme файла!

Это не приемлемо. Должна быть золотая середина между грудами бумаг технической спецификации и её отсутствием, как таковой. И на самом деле она есть. Эта золотая середина — незаметный и скромный Readme файл.

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

Начиная с написания Readme файла в самом начале, вы создаёте для себя ряд существенных преимуществ:
  • Самое важное, что вы даёте себе возможность обдумать проект, без необходимости менять код каждый раз, когда вам приходит на ум что-то сделать по-другому или, например, выбрать что же будет в Public API. Помните то ощущение, когда вы впервые начали писать автоматизированные тесты для кода, и осознали, что вы поймали все возможные типы ошибок, которые, в противном случае, могли бы прокрасться в вашу базу кода? Вот это же самое ощущение вы испытаете, если напишите Readme файл для вашего проект до того, как приступите непосредственно к написанию кода.
  • А ещё, у вас сразу под рукой будет замечательная документация, как побочный продукт написания Readme файла для того, чтобы определить то, что вы хотите реализовать. И вы увидите, что писать этот документ гораздо легче и приятнее, когда вы только-только приступили к проекту и ваше возбуждение и мотивация находятся на максимуме. Писать же Readme задним числом чертовски скучно и вы точно упустите какие-то важные детали, если так поступите.
  • Вы получите даже ещё больше пользы от вашего Readme файла, если вы работаете в команде. Если все в команде имеют доступ к этой информации до того, как вы закончили писать свой код, они могут с уверенностью начинать работу над своими проектами, которые будут взаимодействовать с вашим кодом. Иначе, если интерфейс взаимодействия не определён, вам придётся или писать код последовательно, или же столкнуться с возможностью переписывания большой части кода.
  • Гораздо проще вести обсуждение основываясь на чём-то записанном. Если ничего не описано, можно бесконечно обсуждать проблему круг за кругом повторяя одно и то же. Такое простое действие, как запись предложенного решения, означает, что у всех есть конкретная идея, которая может быть оспорена и повторена впоследствии.

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

Примечания:
  1. Переводы названий техник разработки программного обеспечения взяты отсюда.
  2. О принципах разработки через документирование рассказывается в выступлении Corey Oordt на PyCon 2011

Share post

Comments 36

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

    Что касается написания документации до начала работ — обычно предпочитаю рисовать схему API/проекта/библиотеки в укрупненном виде на доске/листе бумаги/в некой программе и в процессе разработки добавлять в нее детали. Если бы я делал это в письменном виде, то ориентироваться было бы тяжелее. По крайней мере мне. Визуально все это воспринимается проще.

    Впрочем необходимость Т.З. в письменном виде для проектов это никак не отменяет. Но в таких схемах и Т.З. обычно рассматриваются разные аспекты работы системы.

    Но … сколько людей, столько мнений. Возможно кому то это действительно будет удобно.
      +5
      Лично я предпочитаю набросать что-то письменно. Причём, это что-то для себя — что-то среднее между описанием того, что получится и технической документацией. Если развить до уровня команды, получается распространение индивидуальных идей и, как их сумма, общее видение того, что получится.
      0
      Документирование в readme мало чем отличается от комментирования на уровне методов, на уровне классов или пакетов. Как и в случае с комментариями — если в вашем проекте есть readme файл, то значит в нем еще достаточно возможностей, для улучшения.

      В целом же, товарищ Tom Preston-Werner, похоже, слабо понимает принципы и ценности, например, XP, где основная идея — как разрабатывать софт так, чтобы он соответствовал пожеланиям клиентов.
        0
        Вообще-то идея в том, чтобы писать Readme до того, как начинать кодировать. Это значит, что ещё нет ни кода, ни, соответственно, комментариев.

        На мой взгляд, эта идея вполне соответствует принципу agile «Непосредственное общение является наиболее практичным и эффективным способом обмена информацией как с самой командой, так и внутри команды.»
          0
          Наиболее практичным способом обмена информацией с командой является «взять и пообщаться с командой», а не сгенерировать документ, который потом необходимо поддерживать. Зафиксировать принятые дизайн решения лучше будет в тестах.
            0
            Согласен, «пообщаться с командой» — это самый эффективный вариант. Правда он не всегда работает, как например, в случае, если члены команды находятся в разных часовых поясах.
              0
              Skype в помощь :)
              0
              Ну да, и по каждому пустяку общаться? Зачем? Если можно сделать Doxygen-like документацию и минимизировать общение членов команды, по вопросам, которые могут быть решены наличием документации.
                0
                По какому пустяку?
                  0
                  Непонятность назначения определенных частей кода, к примеру
                    +2
                    В этом случае необходимо делать рефакторинг, а не писать комментарии, объясняющие плохо написанный код. Мало того, что это накапливающийся технический долг, так еще и комментарии устареют и будут врать через 3-4 итерации.
                      –1
                      Вы случайно не из той категории программистов, которые утверждают, что комментарии в коде это лишнее?
                        +4
                        Комментарии полезны если описываешь public API и не показываешь код. Но у них другое предназначение, этот кейс я упоминал ниже в одном из комментариев. Ок, еще полезны в парочке экзотических случаев. В большинстве же своем комментарии пишут там, где нужно было бы просто подумать над именами и разделить по функциям. В том числе, когда код не понятен.
                          0
                          Комментарии полезны если описываешь public API и не показываешь код

                          Вам не кажеться, что в любом случае стоит описывать публичный интерфейс если он не является тривиальным?(например: кидает исключения, выполняет какую-то специфическую операцию имя которой сложно впихнуть в имя функции и т.д.)
                          Меня комментарии часто выручали, даже в собственном коде. Например когда разбираешь формат файла какой-нибудь программы с кучей эмпирически полученных констант. Да уже через месяц не вспомнишь кк эти константы были вычислены и откуда они взялись.
                          У меня много примеров, когда комментарии были бы очень к месту и их там не было. И очень мало примеров, когда комментарии повторяли код.

                            +1
                            Нет, не кажется. Если он кидает исключение — в Java это документируется throws декларацией. Могу прокомментировать и специфическую операцию, и константы, если будет пример. Я понимаю весь скептицизм, сам такой был, пока не показали, как действительно можно писать самодокументирующийся код и не поводили за ручку, тыкая в разные места приговаривая «э-э-э, зачем комментарий, сделай вот так!».
                              –1
                              Ну вот про «сам такой был» не надо. Я умею писать само-документирующий код, но это не всегда возможно\целесообразно. Ваша точка зрения мне ясна, я с ней не согласен. Как не согласен с Вами и Стив МакКонел, если это Вам о чем то говорит.
                                +2
                                А с вами Кент Бек. Впрочем, ладно, пишите как хотите, не мне же потом этот код суппортить, надеюсь:)
                          +3
                          Если вам потребовалось что-то комментировать, то лучше сразу переписать непонятный кусок кода так, чтобы было сразу понятно, что и как работает. Созданы тысячи способов как написать не говнокод
                            –4
                            И все эти тысячи способов разлетаются в пух и прах при столкновении с реальностью.
                              0
                              Действительно, способы то есть. Но где гарантия, что не нарушился функционал? — Тестирование. Если затраты на этот производственный цикл существенно превышают затраты на оставление коментария (что чаще всего бывает), то к рефакторингу редко прибегают, если система уже емкая по функционалу…
                                0
                                Накладные расходы на тестирование не идут ни в какое сравнение с будущими расходами на переписывание огромного куска года, который с годами обростает такими костылями, что проще выкинуть и переписать заново. Так вот, переписывание заново в основном идет за счет разработчика. А рефакторинг легко производится за счет заказчика.

                                Не оставляйте даже минимальную затравку говнокода, она имеет свойство разрастаться и заражать остальные участки кода.
                +1
                Да нет, как раз комментирование на уровне методов — это совсем не то же самое, что readme.txt. Файл readme — он для пользователей, а не для программистов. Пользователям глубоко неинтересно внутреннее устройство приложения, названия методов, иерархия классов, типы переменных… Это все можно описывать в документации, чтоб другим программистам было легче потом с этим кодом работать. А пользователям — им нужно знать что делает ваша программа, как ею пользоваться и какие проблемы она помогает решить. Все.
                  +2
                  Если пользователю требуются что-то прочитать, чтобы понять, как оно работает или как его запустить — значит юзабилити программы можно улучшить либо упростить способ установки/запуска. В идеале пользователь ничего не читает, а может пользоваться программой с первых секунд.
                    0
                    Сильно зависит от решаемой задачи.

                    Если задача тривиальная (простой калькулятор), то в самом деле, можно пользоваться нормальной программой с первых секунд — все необходимые знания у 97% пользователей уже есть. Для более сложных задач (сложный редактор, система управления технологическим процессом, хитрая база данных, бухгалтерская, например) может потребоваться не только чтение инструкции, но и куры обучения на несколько месяцев. Потому что большинство людей просто не знакомы с решаемой задачей и даже польностью оптимизированный под эту задачу интерфейс им не поможет — они просто не знают, зачем он нужен.
                      +1
                      Обучение методике/принципам/etc, которые необходимы для использования продукта это отдельный продукт (будь то курсы или книга или ...), со своей целевой аудиторией, задачами и, иногда, жизненным циклом. И уж тем более это не readme файл, который Том призывает писать в самом начале проекта. Впрочем, его понять можно — он описывает все в контексте гитхаба, чтобы люди начали добавлять readme в свои проекты и тем самым привлекать новых людей в проекты (и гитхаб). Другое дело, что хак, а хаки имеют тенденцию накапливаться и бить по лбу своих создателей.
                        +2
                        Автор статьи имел в виду примерно следующее — «выскажите вначале человеческим языком то, что хотите воплотить в коде».

                        Например, «Это будет библиотека для работы с графикой, она позволит быстро получить PNG-файл с изображением заданного размера. Изображение может включать прясоугольники, круги и фрагменты других изображений».

                        Всего пара строчек, а уже становится понятным, что, зачем, с какой функциональностью. Многие не парятся над тем, чтобы это записать, а потом ведь даже тестеру не отдать результат — тот просто не поймет, что за непонятный софт ему принесли и на что его проверять.
                +1
                Я обычно создаю файлик TODO
                  +8
                  Человек описал типичный feature-файл из BDD или user-story из Scrum и назвал его «новой методологией». Обожаю, когда люди не изучившие важных аспектов «хаемых» систем начинают придумывать новые, решающие те же проблемы тем же путем :-D
                    0
                    То, что описывает Том, это не Scrum, т.к. бэклог с историями на реализацию, не хранится в репозитории кода, и не совсем BDD, т.к. менее детально — не определяет поведение методов в каждом случае, и понятно и команде разработчиков — кто, что и как собирается реализовывать, и пользователю — после окончания реализации кода Readme файл остается. Естественно, надо и к этой практике подходить с умом.

                    А вообще, agile методики, на то и agile методики, что не определяют обязательных правил, которыми надо руководствоваться: если вам это удобно и приносит пользу, используйте, если нет — не используйте. :)
                      0
                      Бэклог с историями не храниться в репозитории кода
                      Почему? Что мешает юзер-стори хранить в коде???

                      не совсем BDD, т.к. менее детально — не определяет поведение методов в каждом случае
                      У Вас какая-то путаница в голове по поводу BDD. Есть 2 типа BDD — спецификационное и сценарное. Первое описывает поведение системы изнутри на примере объектных спецификаций, второе описывает поведение системы снаружи на примере поведенческих сценариев всей системы в целом. И я говорю про сценарный BDD, который подходит для реализации желаний Тома намного лучше нежели Readme файл:
                      github.com/knplabs/mink-demo/blob/master/features/search.feature
                        0
                        Как только появилась MS VS 2010, мы стали использовать TFS, который позволяет хранить UML диаграммы (вы не поверите, но мы их рисуем), User Story (да, да, именно они описывают хотелки пользователей с описанием ценности для бизнеса), Test Case (куда надо тыкать, чтобы убедится, что хотелка работает именно так, как ожидает пользователь), и… Ну да, у нас в TFS хранится и код, который привязан к диаграммам, хотелкам и Test Case. И при этом в SharePoint хранится куча Guidline, инструкций, документов. Ведь все упирается в размер проекта. Если у вас dll реализующая 2-3 функции, то и файл readMe при правильной разработке публичного интерфейса может оказаться лишним. А если вы разрабатываете систему на 10к+ пользователей, то может и то что я описал окажется мало.
                      +1
                      Даешь методологию «Разработка основанная на About...»
                        0
                        Может вначале надо было бы определить, что должно войти в Readme файл, а потом уже призывать заменить им документацию? В процессе определения может выясниться, что это та же самая дока, только собранная в одном файле, и на самом деле мы имеем дело с таким себе спецификационным аналогом универсального метода «сделать все зашибись».
                          +1
                          Как раз недавно видел код какого-то гема от Р.Бейтса, созданный по этой методологии. Она не исключает TDD, BDD и SCRUM, а только лишь улучшает их. Отличная методика. Спасибо, что довели это до русскоязычных программистов.
                            0
                            Смешная статья.

                            «Все эти TDD, BDD… не имеют смысла, а вот зато мой метод классно работает» — и дальше описывает ту же идею, что лежит в основе TDD и BDD: сначала подумать и описать, а потом уже кодировать. Идея сама по себе правильная, но такое претензионное начало настраивает читателей против автора и говорит о его неосведомлённости.
                              0
                              Этот README-файл, это же Vision & Scope Document.
                              В самом начале проекта действительно стоит чуть-чуть подумать в голове и на бумаге, поконцептуализировать. На данном этапе обратная связь может быть богаче от простого обсуждения, чем от кода.
                              Шаблон VSD от Karl Wiegers содержит ряд правильных вопросов, над которыми полезно подумать.
                              Но не увлекаться, конечно.

                              Кстати, возможны и другие формы размышления о концепции. Например, Personas или System Metaphor из XP.

                              Only users with full accounts can post comments. Log in, please.