В этом месяце ко мне пришли три легаси проекта на аудит и разработку стратегии развития. Во всех трёх нет описания, документации и даже README. С автором одного из проектов связи больше нет.
В мире Open Source без README никуда — содержимое этого файла автоматически отображается в качестве описания на странице репозитория с кодом на GitHub. В качестве синтаксиса чаще всего используется Markdown, что позволяет использовать заголовки, ссылки, копируемые команды и примеры кода.
В мире продуктов, написанных “для себя” или “для клиента” часто описания нет. Или README без изменений унаследован от фреймворка, на котором собран проект. Это уже первая подсказка, но дальше разбираться нужно самостоятельно.
Разработчику кажется, что он — первый, последний и единственный посетитель репозитория. Нет смысла писать эти инструкции — для кого? А через несколько лет новый разработчик смотрит на папку с кодом и чешет затылок.
Что писать в README:
– Название проекта.
– Описание — ответ на вопрос, а что этот код делает и для чего.
– Зависимости и библиотеки, описать что под капотом и в какой среде это работает, требования к железу и среде.
– Архитектура — как это устроено?
– Инструкция по установке и первому запуску.
– Инструкция как разворачивать на сервере, если отличается от локального запуска.
– Ответьте на все вопросы, которые задаст новый разработчик в первый день работы с проектом.
– Примеры использования, типичный рабочий процесс.
– Полезные ссылки на официальную страницу, документацию, статьи.
– Контакты — с кем связаться, кто в курсе продукта, кто заказчик.
– Инструкция как вносить правки в код.
– Лицензионное соглашение для этого кода и для зависимостей (если применимо).
К каждому исходному коду должен прилагаться файл README с описанием. Новый проект следует начинать с этого файла. В существующих проектах файл следует обновлять при изменениях или поступающих вопросах.
Я как раз собираюсь писать README для одного из проектов.
А для вдохновения коллекция лучших примеров, собранных по всему GitHub.