Конвенции по проекту

В любом хоть более-менее сложном проекте, над которым работает, пожалуй, больше двух людей, стоит заранее договориться о некоторых правилах касающихся кода и зафиксировать их, дабы поддерживать порядок было легче. Такие конвенции могут отменяться со временем, или могут возникать новые, в любом случае их стоит с самого начала периодически обдумывать.

Содержание

1. Конвенции по гиту
2. Конвенции по наименованию файлов и директорий
3. Конвенции по именованию классов, функций и переменных
4. Конвенции по документированию
5. Конвенции по коммуникациям
6. Конвенции по фронтендам
7. Прочие конвенции

1. Конвенции по гиту.

1. Конвенция наименования веток. Указать типы существующих веток, их назнычение, выделить шаблон для правильного названия.
2. Конвенция по наименованию коммитов. любой коммит обязательно должен принадлежать какой-нибудь таске. Пример: {полное имя задачи с номером}/${комментарий о проделанной работе если необходимо}.
3. Конвенция для push в основныые ветки (dev/master/prod etc.). В основную ветку код попадает только через ПР. Не важно какой ранг и роль у того, кто этот коммит делает.
4. Конвенция принятия ПР. Для попадания в основную ветку обязательно должно быть необходимое число подтверждений (approve), обычно 1 или 2.
5. Конвенция по гиту. Описать стандарты работы с гитом (указать флоу, используем squosh, rebase, или мержим и пр.)

2. Конвенции по наименованию файлов и директорий

1. Конвенция о первой букве. Нужно договориться, что значит большая буква в наименовании файла или директории. Если ничего не значит, то нужно договориться все называть либо с маленькой буквы, либо с большой.
2. Конвенция по именам директорий и файлов. Имя пакета должно совпадать с именем файла, содержащим главную сущность пакета или иметь обобщённое название, если все файлы в пакете содержат сущности одного ранга.
3. Конвенция по подчеркиванию множественного числа в нейминге. Обобщённое название не должно содержать букву «s» обозначающую множественное число, так как это не несет дополнительного смыла. Если есть директория models, то на этом уровне исключена возможность появления директории или файла model и наоборот, поэтому выбираем более короткое название.
4. Конвенция по именам файлов и сущностей. Имя файла должно содержать имя главной сущности этого файла или иметь обобщённое название, если все переменные в пакете одного ранга.
5. Конвенция о суффиксах. Нужно договориться о политике суффиксов в названиях, в каких случаях обязательно их использование. Я люблю префиксовать следующее: *Service, *Model, *Dto, *Store, *Type, *Component, *Converter.
6. Конвенция о префиксах. Нужно договориться о политике использования нейминга главной сущности в нейминге файлов пакета. Например, если у нас есть пакет SuperPage, в котором файл с главной сущностью SuperPage.tsx и в этом пакете есть файл с формой, которая используется главной сущностью, то этот файл можно назвать Form.tsx или MainPageForm.tsx. Несмотря на то, что мы дублируем название пакета во втором варианте, вариант с MainPageForm.tsx мне нравится больше, так как позволяет проще навигироваться по файлам в современных IDE с использованием быстрого поиска по имени файла.

3. Конвенции по именованию классов, функций и переменных

1. Конвенция по наименованию в коде. Можно ссылаться на McConnel «Clean Code», тема широкая, но стоит обозначить основные правила в наименовании.

4. Конвенции по документированию

1. Конвенция по внутреннему документированию. Договориться и зафиксировать, как будет вестись внутренняя документация в коде, readme файлах, фигме и прочее. Что документируем, а что нет.
2. Конвеция по документированию описания модулей. Должны быть описаны основные модули и их назначение.
3. Конвенция по документированию стандартов применяемых к модулям/сервисам. Классифицировать модули/микросервисы приложения и описать основные стандарты, применимые к ним.
4. Конвенция по документированию коммуникаций между сервисами. Описать взаимодействие между модулями и стандарты коммуникации между ними.
5. Конвенция по документированию используемой документации. Описать вид используемой документации и в каких местах она применяется.
6. Конвенция по документированию нейминга распространённых сущностей. Договориться: все, что должно или может повторяться -- зафиксировать и ввести конвенции по неймингу (например таблицы, сущности, сервисы, слои и пр.).

5. Конвенции по коммуникациям

1. Конвенция по каналам связи. Определить и описать список каналов связи и случаи их использования.
2. Конвенция по времени отклика. Характерное время отклика членов команды не должно превышать 30 минут.
3. Конвенция по периоду доступности. Каждый член команды должен явно указать период доступности в рабочие дни, в течении которого будет работать конвенция по времени отклика.
4. Конвенция по статусам на ежедневных митингах. Ежедневные митинги не должны занимать больше 20 минут, иначе они становятся не эффективными.
5. Конвенция по величине группы обсуждения по специфическому вопросу. Если вопрос затрагивает меньше 50% команды, то он не должен обсуждаться на общих митингах.
6. Конвенция по размеру групп для обсуждения. Собирать группы количеством участников более 10 (15) часто не слишком эффективно, выгоднее предложить заранее описать вопросы и докладчики постараются на них ответить. Если тема важная, то следует сделать процесс итерационным, где после каждой встречи опять предлагается зафиксировать вопросы, а докладчики на них ответят в следующий раз.
7. Конвенция фиксации договорённостей. Что не записано, того нет. Все конвенции, архитектурные описания и прочие договорённости обязательно должны быть зафиксированы и быть всем доступны для ознакомления и обсуждения. Если обсуждение задачи занимает больше часа, то нужно назначать кого-нибудь, кто её задокументирует. Все нетривиальные или нестандартные решения должны быть задокументированы.

6. Конвенции по фронтендам

1. Конвенция по организации роутинга. Любая страница, которая может быть открыта независимо от других страниц, должна обладать своим уникальным url-адресом.

7. Прочие конвенции

1. Конвенциия по white list допустимых технологий. Описать белый лист основных технологий, используемых на проекте (например, языки программирования, типы баз данных и пр.) и описать причину выбора.
2. Конвенция о средах разработки (форматах). Задуматься об унификации высокоуровневых инструментов и используемых форматах- сред разработки (в том числе для дизайнеров, для документов и схем, типов репозиториев и пр.). Описать, в каких случаях какие следует применять.
3. Конвенция по кроссплатформенности. В микросервисах и модулях должны быть требования для локальной развёртки, а так же инструкции по запуску на допустимых устройствах (например, чтобы не было ОС-специфических скриптов), либо в крайнем случае должны быть явно описаны допустимые ОС или среды.
4. Конвенции по agile. Стандартные agile понятия тоже должны быть стандартизированы (definition of done, definition of ready, формат оформления багов, тасок, тип комментариев в тасках, уведомление бизнеса о релизе и пр.)
5. Конвенция по конфигурациям. Унифицировать стандартные конфиги для различных инструментов контроля качества кода.
6. Конвенция по средствам и целям мониторинга. Стандартизация мониторинга различных окружений, возможно главные для бизнеса метрики, важные метрики для разработчиков и пр.
7. Конвенция по логированию. Стандартизировать формат логов.
8. Конвенции по CI/CD. Стандартизация процессов CI/CD (например унифицированный контейнер, унифицированные pipelines, отдельное описание специфических отличных от стандартных мест).
9. Конвенция по инфраструктуре. Стандартизация инфраструктуры и её настроек (унификация настроек и подходов к проектированию loadbalance, namespaces in kubernates, пр.)
10. Конвенция по затратам на инфраструктуру. Перед выполнением некоторых задач нужно в том числе оценивать стоимость затрат на инфраструктуру.
11. Конвенция по самообразованию — нужно всем тратить время на самообразование и отчитываться об этом. Например, заводится список книг и все члены команды должны уделять 30 минут в день на прочтение одной из книг. Это влияет на культуру внутри команды.