Вы когда-нибудь задумывались, как сделать ваш репозиторий более читабельным и снизить начальный уровень для новых участников в вашей команде? Как сократить время, необходимое для адаптации новых людей, и ограничить вопросы, которые задают внешние люди, которые хотят использовать ваши решения или внести свой вклад? Или как облегчить себе задачу воссоздать развивающуюся экосистему после изменения образа / смены ноутбука? Недавно я проанализировал множество репозиториев (частных и открытых) и обнаружил, что некоторые из них гораздо более удобны для новых участников, чем другие. Что делает их такими особенными? Несколько мелких вещей, которые вы можете реализовать в своем проекте с действительно небольшими затратами времени и усилий. Ниже вы можете найти 6, на мой взгляд, самых полезных советов по улучшению репозитория кода уже сегодня.
# 1 Readme
Наверное, для многих из вас это очевидно. Но в то же время это так важно, что я не могу упустить этот момент в своей статье. Readme - это файл в корне вашего проекта git, в котором вы должны описать наиболее важную информацию о нем. Какую информацию там размещать? Однозначно, основная цель репозитория - зачем он был создан, какова его цель, кто отвечает за этот проект. Лично я также большой поклонник добавления раздела с конкретной информацией о том, как установить, разработать и развернуть код в репо. Да, я знаю, что в большинстве случаев вначале это будет примерно так:
git clone <repository-address> npm install npm run start
но помните, что наши проекты не всегда так просты! Когда ваш репозиторий растет и вы начинаете использовать субрепозитории, монорепозитории, микро-интерфейсы, сложные зависимости, докеры или расширенную логику для развертывания, первый запуск приложения может стать кошмаром для нового участника, особенно если это человек с другой технический фон, чем ваш. Добавление в файл readme конкретной информации об этих процессах (особенно сформированной в виде цепочки команд для вызова в терминале) не только снижает начальный уровень для внесения вклада в ваш репозиторий, но также сокращает время, необходимое для адаптации нового человека или ответа на вопросы от другие команды в вашей компании. И это должно занять менее 5 минут (в самом простом случае вы можете просто скопировать и вставить команды, которые вы используете каждый раз для запуска проекта из терминала в файл readme). Совершенно того стоит - не правда ли? Если вам нужно вдохновение, проверьте, например, Github-changelog-generator - действительно хороший пример хорошего ридми-файла!
# 2 Скрипты в package.json
Package.json - следующий, очень важный файл почти в каждом проекте на основе JS / typescript. Это файл, в котором вы можете определить версию, имя и зависимости для проекта. Благодаря этому вы можете просто позвонить npm install или yarn, чтобы установить все зависимости, необходимые для вашего проекта (в правильных версиях!). Как фронтенд-разработчик, вы, вероятно, используете это все время. Но есть также раздел, который, к сожалению, менее популярен, и я пишу здесь о скриптах. Это не что иное, как список "ключ-значение", в котором вы можете определить свои собственные имена для некоторых команд. Когда вы используете, например, Angular, некоторые из них будут сгенерированы во время инициализации проекта - например, start или test. Хотя я настоятельно рекомендую вам добавить свои собственные. Если у вас есть специальная команда для запуска модульных тестов, добавьте ее в скрипты. Если вы используете какие-либо инструменты для проверки стиля кода, добавьте его в этот раздел. Если вы используете докер, добавьте скрипт для его локального запуска и там. Если честно, здесь должны быть размещены почти все команды, которые вы используете в терминале. Преимущества как минимум два: все полезные команды задокументированы, поэтому новый человек в команде может легко проверить, какие действия возможны, и вы получите короткие, легко запоминающиеся и вводите псевдоним для вызова в терминале.
# 3 Чванство
Определение и документирование API может оказаться сложной задачей. К счастью, у нас есть нечто, называемое чванством - набор инструментов с открытым исходным кодом, созданных на основе спецификации OpenAPI, которые могут помочь вам разрабатывать, создавать, документировать и использовать REST API. Благодаря им вы можете создать веб-страницу со всеми конечными точками, определенными с их параметрами запроса, параметрами тела, схемами ожидаемого ответа и т. Д. Более того, вы также можете тестировать вызовы прямо с этой страницы. Вам не нужно копаться в исходном коде, чтобы понять API. А пользоваться или менять сервис намного проще, не правда ли? Скажем несколько слов о том, как реализовать их в жизненных циклах нашего проекта. Есть два основных подхода к определению чванства: как контракт перед разработкой или автогенерация на основе созданного служебного кода. У обоих есть свои плюсы и минусы. Определение файла swagger в качестве контракта API перед тем, как касаться кода, позволяет нам параллельно работать между разными командами, зависящими от этой службы, и создавать типы машинописных текстов на основе этого (полезно, когда ваш бэкэнд написан на Node, и вы хотите обмениваться типами между репозиториями). Но также требует больших усилий - все конечные точки должны быть определены вручную, и некоторые последующие изменения в обслуживании могут быть пропущены (разработчики должны помнить об изменениях в двух местах). С другой стороны, вы можете использовать аннотации для автоматического создания файлов swagger на основе исходного кода - используя библиотеки, доступные почти для всех языков. Благодаря этому вам не нужно беспокоиться об обновлении документации, но всем потребителям нужно дождаться, пока рабочая версия API начнет свою работу, и некоторые комментарии. Тем не менее, независимо от того, какой вариант лучше в вашем случае, использование чванства определенно может вывести вашу документацию по API на совершенно новый уровень.
Примечание. Очень часто ваш контракт на чванство определяется в отдельном репозитории. Если это так, не забудьте добавить ссылку на файл Readme в основном проекте. Будьте добры к другим, не заставляйте их искать это (или, что еще хуже, упускайте знания, которые существуют)!
# 4 Тесты
Наверное, здесь самое удивительное. Но хорошо написанные тесты могут быть гораздо лучшим источником знаний о репозитории, чем традиционная документация. Документы могут лгать - никогда не кодируйте! Когда у меня возникают проблемы с пониманием какой-либо части системы, я всегда смотрю на модульные или функциональные тесты для этого. Это простой способ проверить, какие варианты использования были предсказаны автором кода и как они должны работать. Хорошие тесты также повышают качество вашего проекта. Двойная победа!
# 5 .nvmrc
Мелочь, но меня радует! Файл .nvmrc позволяет определить и задокументировать версию узла, используемую в проекте. Это всего лишь одна строка, но тот, кто боролся с нарушенной установкой и не понимал, что не так, будет признателен. Тем более, что ошибки, выводимые в терминале, вообще не указывают на неправильную версию узла! Используя .nvmrc, достаточно вызвать nvm use перед npm install, и будет использована правильная версия узла. Такой маленький, такой милый!
# 6 Правила стилизации кода и автоматизация
Пожалуйста, не тратьте свое и чужое время на ручную проверку отступов или правил форматирования. И запишите их вместо того, чтобы говорить Мы всегда так поступаем во время проверки кода. Я знаю, что пробелы против табуляции - священная война в программировании, но вы должны решить эту битву в своей команде. Добавьте в репозиторий такие инструменты, как eslint или красивее и набор правил. Автоматизируйте проверки. Проверьте свое форматирование при предварительной фиксации или создании запросов на слияние. Четко определяйте правила - не только в уме. И пусть компьютер выполняет эти простые проверки - он лучший в этом деле!
Резюме
Конечно, представленный выше список не исчерпывающий, и есть еще много способов улучшить вашу кодовую базу, чтобы сделать ее более удобной для новичков. Но все представленные мной советы легко реализовать и, по моему личному мнению, имеют огромное влияние на людей, которые хотят начать работу с вашим репозиторием. Надеюсь, статья окажется для вас полезной! Если да, нажмите кнопку «хлопнуть» или оставьте комментарий ниже. Удачного кодирования!
