За последнюю неделю я просмотрел код четырех проектов на Восьмой платформе. Между проектами была общая нить, и это было полное отсутствие документации. Кажется, это постоянная проблема почти во всех проектах, в которых я участвовал за последний год, и ее нужно остановить.
Теперь я знаю, что как разработчики и создатели мы ненавидим документацию, и я это понимаю. Мечта о написании настолько прозаичного кода, что не требуется никакой документации, пока остается лишь мечтой. Даже небольшие проекты — это гораздо больше, чем просто код. Этот пост не является разглагольствованием об отсутствии функциональной документации или схем. Agile правильно пытается ограничить это.
Каждому проекту нужен как минимум актуальный файл README.
Что такое файл README
Файл README — это файл, написанный с использованием синтаксиса Markdown. Он используется для передачи некоторой базовой информации о вашем проекте и о том, как он работает. Подробная информация, например, как его клонировать, необходимое программное обеспечение или библиотеки, а также как собрать и запустить проект. README обычно находится в корне папки проекта. Этот контент используют системы контроля версий на основе Git, такие как GitHub. Они отображают его, когда вы попадаете на страницу хостинга проектов.
Разница между хорошим и плохим файлом README
Остановитесь и подумайте о том, что вы чувствуете мысленно, когда ищете проекты на GitHub. Доверяете ли вы проектам, на странице которых нет подробностей? Или вы больше доверяете страницам с множеством полезных деталей и скриншотов?
Частные, коммерческие, проекты ничем не отличаются. Git позволяет мне видеть, кто работал над проектом. На их репутацию для меня влияет то же самое, что и на вас, когда вы попадаете в проект GitHub. Влияние на репутацию команд разработчиков и разработчиков программного обеспечения еще больше. Когда вам платят за то, чтобы начать проект с целью его сдачи, отсутствие README или любого базового проектного документа наносит ущерб. Я бы посоветовал любому клиенту потребовать этот документ в любом согласованном контракте или соглашении или приостановить платеж до его предоставления.
Почему? Ну, здесь есть пара мыслей. Во-первых, это продуктивность разработчиков. Если другой разработчик берет на себя проект, он хочет как можно скорее начать работу с кодом. Они не хотят тратить свое время на выяснение того, как им нужно настроить свою машину. Какую версию стека они должны использовать? Какие библиотеки и версии необходимо установить? Некоторые фреймворки делают это тривиальным вопросом. Но некоторые позволяют настраивать проекты и среды различными способами. Опять же, это имеет значение, если вы передаете проект между разработчиками или командами и платите дневную ставку. Вы фактически удваиваете свои расходы. Другая мысль заключается в том, что если разработчик (разработчики) не может быть достаточно профессиональным, чтобы добавить README, то в каком состоянии находится код? Это может показаться резким замечанием, и это не всегда так, но оно заслуживает внимания.
Как всегда, вы можете подумать об этом и с инвестиционной точки зрения. Если вам нужно пройти процедуру Due Diligence без базовой документации, вам нужно будет защитить это.
Вот отличный шаблон от GitHub. Если вам нужно, идите и скопируйте его и заполните пробелы. Не будьте разработчиком или командой, которые пытаются скрыть или использовать свои знания о проекте для получения финансовой или репутационной выгоды. Это просто заставляет вас выглядеть плохо.
