Readme Driven Development

Нац Нац

Disclaimer: Это довольно небрежный перевод статьи Тома Престона-Вернера, со-основателя GitHub, о важности написания README.

Я много слышал о TDD и BDD, Экстремальном программировании и SCRUM, а также о стендап-митингах и других всяких там методах разработки лучшего программного обеспечения, но все это не имеет значения, если только программное обеспечение, которое мы строим, не отвечает потребностям тех, кто им пользуется. Окей, перефразирую это по-другому. Совершенная реализация неправильной спецификации бесполезна. По тому же принципу красиво созданная библиотека без документации также по-факту бесполезна. Если ваше программное обеспечение решает неправильную проблему или никто не может понять, как его использовать — значит происходит что-то очень нехорошее.

Хорошо. Итак, как мы решаем эту проблему? Это проще, чем кажется, и эта штука достаточно важна, чтобы выделить ей отдельный абзац.

Сначала напишите README.

Перво-наперво, прежде чем писать какой-либо код, тесты, перед анализом поведения или расписывания юзер-сторь и вообще прежде ВСЕГО пишите Readme. Я знаю, я знаю, мы программисты, черт возьми, а не технические писатели! (( ͡° ͜ʖ ͡°), прим. редактора) Но вот тут-то вы и ошибаетесь. Существование Readme абсолютно необходимо для написания хорошего софта. Пока вы не напишете о своем программном обеспечении, вы не представляете, что за код вы будете педалить. Между битвой с Waterfall-подходом и Великим Принятием Agile что-то протерялось. Не поймите меня неправильно, Waterfall слишком много на себя берет. Огромные системы, расписанные в мельчайших подробностях, в конечном итоге оказываются ПЛОХИМИ системами, описанными в мельчайших подробностях. Мы были правы, когда отказались от него. Но то, что заняло его место, слишком далеко уводит нас от сути. Теперь у нас есть проекты с короткой, плохо написанной или полностью отсутствующей документацией. В некоторых проектах нет даже Readme!

Это неприемлемо. Должно же быть нечто среднее между полотнами технических спецификаций и их полным отсутсвием. А ведь есть. То самое нечто среднее это наш верный старый друг — скромный Readme.

Важно отличать Readme Driven Development от Documentation Driven Development. RDD можно рассматривать как подмножество или ограниченную версию DDD. Ограничивая ваши диз.доки одним файлом, который предназначен для ознакомления с ПО, которое вы разрабатываете, RDD уберегает вас от синдрома DDD-скатившегося-в-waterfall, наказывая вас за длинную и слишком детальную спецификацию. В то же время он вознаграждает вас за то, что библиотеки остаются небольшими и модульными. Эти мелкие, простые изменения подталкивают ваш проект в правильном направлении, так вы сможете обходиться без громздкого процесса, необходимого для проверки того, что вы все делаете правильно.

Начав с написания Readme, вы даете себе некоторые существенные преимущества:

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

Рассматривайте процесс написания Readme для вашего проекта как акт истинного творения. Здесь вы должны выразить все свои блестящие идеи. Этот документ должен стоять обособленно, как свидетельство вашего творчества и выразительности. Readme должен быть самым важным документом в вашей кодовой базе.

Начинать работу с написания Readme — это правильно.