RDD — это крайне простая практика. И здесь «DD» может означать «минута на освоение и вся жизнь для мастерства». Но, к счастью, не в этом случае.
Пишите Readme в первую очередь. Вот в принципе и все. Но почему?
Всякий раз, когда вы начинаете программный проект, будь то ваш личный проект или принадлежащий компании на которую вы работаете. Вы должны (по возможности) стремиться писать понятный, поддерживаемый код, который можно использовать многократно.
У каждого есть своя точка зрения о том какие инструменты, практики и процессы способствуют улучшению программного обеспечения. В конце дня ваша программа по-прежнему должна работать. Это легко забыть, если слишком сильно сосредоточиться на том, чтобы закончить её или использовать все красивые решения.
Работа программы это не только о её код. Если никто не может использовать программу, потому что не знает как, то не важно содержит ли она кучу ошибок или не содержит ни одной.
Скромняга Readme
Readme — это самый важный файл во всем проекте. Он должен содержать краткий обзор задач проекта (его назначение, зачем он создан), инструкции по установке, известные проблемы и достаточно подробное описание того, что нужно сделать чтобы быстро начать пользоваться программой, для тех людей, которые никогда до этого не пользовались вашим программным обеспечением.
Не поймите меня неправильно, Readme это не вся документация которая только может вам понадобится. Однако, вы можете удивиться, узнав, что небольшой Readme охватывает подавляющее большинство проблем и вопросов, тех людей, которые его читают.
Если вы напишете свой Readme, до того как приступить к написанию кода, вы получите несколько крутых преимуществ:
- Вы получите полный обзор того, какую функциональность вы должны реализовать, и как вы можете её обеспечить с помощью публичного API. В этот момент, до того как вы начали писать код, вы можете легко менять архитектуру проекта.
- Когда вы начнёте писать код, вы будете иметь чёткое представление, что и как именно должно быть реализовано.
- Readme также может выступать в качестве индикатора для вас самих и других людей о прогрессе в разработке проекта.
- Если вы работаете в команде с другими разработчиками, у вас будет почти идеальная спецификация. И другие разработчики смогут подключаться к проекту с меньшим страхом того, что спецификация может измениться в процессе разработки.
- Обсуждения очень важны. И гораздо легче обсуждать, то что записано. Легче изменить Readme чем бесконечно спорить о том, как что-то должно работать, когда и если вы до него доберётесь.
- Как правило, наиболее активная и захватывающая часть проекта в начале. Это лучшее время, чтобы написать небольшой объем документации, который впоследствии будет служить Вам и другим людям. Позже написание документации всегда затягивается и я очень удивлюсь, если в итоге, вы будете помнить все детали реализации и известные проблемы.
- Изменяются даже самые продуманные проекты, надеюсь, что эти изменения будут происходить не из-за каких-либо проблем. а для добавления новой функциональности. Но они все равно неизбежны и как правило происходят путем развития. Единственный документ (надеюсь, в системе контроля версий) может выступать идеальной средой для связи между изменениями по мере того, как они происходят. Также стоит отметить, что записывать изменения по мере того как они происходят гораздо проще, чем пытаться вспомнить их все потом.
Добавление RDD в существующий проект требует отдельной статьи. Но на данный момент, надеюсь, у вас появилась пища для размышлений.
Автор: DuDDiTs
