RDD — это крайне простая практика. И здесь «DD» может означать «минута на освоение и вся жизнь для мастерства». Но, к счастью, не в этом случае.Пишите Readme в первую очередь. Вот в принципе и все. Но почему?
Всякий раз, когда вы начинаете программный проект, будь то ваш личный проект или принадлежащий компании на которую вы работаете. Вы должны (по возможности) стремиться писать понятный, поддерживаемый код, который можно использовать многократно.
У каждого есть своя точка зрения о том какие инструменты, практики и процессы способствуют улучшению программного обеспечения. В конце дня ваша программа по-прежнему должна работать. Это легко забыть, если слишком сильно сосредоточиться на том, чтобы закончить её или использовать все красивые решения.
Работа программы это не только о её код. Если никто не может использовать программу, потому что не знает как, то не важно содержит ли она кучу ошибок или не содержит ни одной.
Скромняга Readme
Readme — это самый важный файл во всем проекте. Он должен содержать краткий обзор задач проекта (его назначение, зачем он создан), инструкции по установке, известные проблемы и достаточно подробное описание того, что нужно сделать чтобы быстро начать пользоваться программой, для тех людей, которые никогда до этого не пользовались вашим программным обеспечением.
Не поймите меня неправильно, Readme это не вся документация которая только может вам понадобится. Однако, вы можете удивиться, узнав, что небольшой Readme охватывает подавляющее большинство проблем и вопросов, тех людей, которые его читают.
Если вы напишете свой Readme, до того как приступить к написанию кода, вы получите несколько крутых преимуществ:
- Вы получите полный обзор того, какую функциональность вы должны реализовать, и как вы можете её обеспечить с помощью публичного API. В этот момент, до того как вы начали писать код, вы можете легко менять архитектуру проекта.
- Когда вы начнёте писать код, вы будете иметь чёткое представление, что и как именно должно быть реализовано.
- Readme также может выступать в качестве индикатора для вас самих и других людей о прогрессе в разработке проекта.
- Если вы работаете в команде с другими разработчиками, у вас будет почти идеальная спецификация. И другие разработчики смогут подключаться к проекту с меньшим страхом того, что спецификация может измениться в процессе разработки.
- Обсуждения очень важны. И гораздо легче обсуждать, то что записано. Легче изменить Readme чем бесконечно спорить о том, как что-то должно работать, когда и если вы до него доберётесь.
- Как правило, наиболее активная и захватывающая часть проекта в начале. Это лучшее время, чтобы написать небольшой объем документации, который впоследствии будет служить Вам и другим людям. Позже написание документации всегда затягивается и я очень удивлюсь, если в итоге, вы будете помнить все детали реализации и известные проблемы.
- Изменяются даже самые продуманные проекты, надеюсь, что эти изменения будут происходить не из-за каких-либо проблем. а для добавления новой функциональности. Но они все равно неизбежны и как правило происходят путем развития. Единственный документ (надеюсь, в системе контроля версий) может выступать идеальной средой для связи между изменениями по мере того, как они происходят. Также стоит отметить, что записывать изменения по мере того как они происходят гораздо проще, чем пытаться вспомнить их все потом.
Добавление RDD в существующий проект требует отдельной статьи. Но на данный момент, надеюсь, у вас появилась пища для размышлений.
Поделиться с друзьями
Комментарии (9)
kvaps
23.06.2016 17:59+4Очень поддерживаю идею автора, всегда, когда есть такая возможность, стараюсь писать readme в первую очередь, так кодить проще и если сразу не напишешь, потом заставить себя куда сложнее, особенно если проект маленький и вряд ли кому-то еще пригодится, кроме тебя...
iroln
24.06.2016 12:34+1Вот что я стал замечать в последнее время. Берут какую-то очевидную вещь и начинают раздувать её значимость, искусственно ставя её в центр всего, словно всё вокруг зависит только от неё. Ну вот, казалось бы, Как из Readme может следовать этот пункт?
Когда вы начнёте писать код, вы будете иметь чёткое представление, что и как именно должно быть реализовано.
Давайте, так, это, мягко говоря, неправда! Я понятия не имею на старте проекта, как именно я реализую что-либо. Особенно если проект научно-исследовательский. Да, мы напишем в Readme "Мы долетим до ближайшей галактики за разумное время" и пойдём писать код. Всё просто, ведь главное, что у нас есть Readme!
Я не говорю, что Readme не нужно, просто не надо из каждой мелочи делать сенсацию. Предлагаю автору написать работу на PhD на тему "Readme Driven Development".
kotbajan
24.06.2016 12:35+1Мне кажется, вы описали принцип «сначала проектируй, потом пиши код». При этом посоветовав использовать файл readme в качестве Project backlog.
nikolay_karelin
24.06.2016 14:12Писать документацию это всегда боль — нужно «подняться над кодом» и постараться объяснить, как и для чего он был написан. Если есть хотя бы внятный README.md — то уже проще работать с проектом ;)
zelenin
по-моему у вас где-то процентов 90 поста потерялось.
DuDDiTs
По-моему вы не переходили по ссылке на оригинал
Drag13
А еще можно переводить твиты… Успех гарантирован.
vladimirbondarev
По моему Вы забыли добавить ссылку на оригинал. Не нашел в Вашей статье первоисточник.
DuDDiTs
Она добавляется под статьей, там где имя автора оригинального текста