Yet another формат описания технических соглашений by Vasilisa Versus. Использую его, чтобы собрать знания о проекте в одном месте, итеративно проводить рефакторинг, онбоардить новых сотрудников и на его базе фасилитировать обсуждения. Ценность состоит из: подхода к тому как с этим документом работать и самой структуры, которая наследуется из проекта в проект.
Каждое правило имеет следующую структуру
## Название секции
Короткое описание секции, что к чему и почему. Если получится выразить в двух-трех тезисах, то идеально!
### Материалы
- [некая рекомендация №1](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882)
- [еще одна рекомендация](https://www.netflix.com/pt/title/81435684)
- [третья рекомендация](https://youtu.be/dQw4w9WgXcQ)
### Правила
<details>
<summary>Правило 1</summary>
Такие правила могут быть спойлерами, внутри которых немного мотивации и примеров
</details>
<details>
<summary>Правило 2 под спойлером</summary>
Если их не много, то это приемлемо, но вы можете оценить читаемость исходника
Еще ниже будет пример собранного документа, который можно копипастить
</details>
- Правило может быть и просто пунктом в списке
- [А еще лучше конечно сделать его ссылкой](/section1/rule4.md)
## Рецепты
<details>
<summary>Как что-то сделать 1</summary>
Гайд может быть прям очень длинным, включать графику и описания шагов
</details>
<details>
<summary>Гайд на что-то</summary>
Гайды конечно первые на разнесение в отдельные файлы
</details>
<details>
<summary>Очередной пример</summary>
Я лично организовывала такое через яндексовую вики, в гитхабвики и confluence
Для большого проекта общее количество материалов было не больше 60 (около 2-3к строк)
Для небольших около 20 (500 строк)
Начинаю всегда с того чтобы держать в одном файле и разношу по мере необходимости.
</details>Коротко гайд для старта:
- Копипастим пример ниже в ваш проект или форкаем репу (или перенесите в вашу базу знаний, как удобнее, советую хранить с кодом)
- Проходимся сверху вниз и заполняем секции правил для текущего состояния проекта
- ЕСЛИ уже есть какие-то гайды, то собираем их в одном месте и причесываем. Если нет, то можно запланировать проработку хотя бы тех, которые есть в примере ниже
- Постепенно накапливаем материалы для рекомендаций и обновляем и актуализируем
Документ в худшем случае заводится и овнится одним человеком который контролирует проект и его состояние. Нужно прилагать усилия, чтобы вовлекать его развивать и поддерживать коллективно, это обязательное условие к использованию. Об этом можно много писать, но если коротко критично минимально на документе завязать несколько процессов: онбоардинг, код ревью и обсуждение подходов к разработке.
Интуитивно любые обсуждения к тому как работаем, будут вестись везде, где это только возможно, что ок, но постепенно будет накапливаться ощущение бесполезности усилий. Конструктивнее подталкивать коллег все фиксировать в некий единый источник истины - возник дискомфорт в работе? Что-то не нравится? Оформи минимально proposal в документ с соглашениями, мы его там на месте обсудим и примем. Сам процесс выслушивания, фиксации и принятия очень стимулирует того, кто столкнулся с чем-то в работе. Это критично важно.
Я предлагаю почаще подталкивать окружающих к тому, чтобы все мысли, идеи и проблемы максимально фиксировались. Нельзя допускать того, чтобы команда постоянно тонула в ощущении безысходности и существовала в страхе конфликта. Когда правила изложены в документе, то они обезличены, а значит можно оспаривать и предлагать что-то еще, без страха столкнуться с тем, что это адресно заденет и будет воспринято как что-то личное. Сравните с кейсом, когда в процессе код-ревью вам пишут переименуй переменную, мы пишем в camelCase VS Мы пишем в camelCase [ссылка на правило]. Точно также это касается и обсуждений в slack, если вы будете использовать документ как медиатор, то это снизит градус накала и позволит выстроить конструктивный диалог.
Изначально документ проектировался как гайд к код-ревью и решал проблему конфликтов в обсуждениях PR. Все соглашения можно разделить на те, которые можно автоматизировать и те, которые мы должны проверять об человека.
Для начала стоит в целом определиться какую роль в вашем проекте играет код-ревью и зачем оно вам. Потом можно собрать основные замечания которые вы там встречаете и выписать их в этом документе.
Я предлагаю кидать ссылку при ревью на доку в ситуациях типовых проблем. Если кто-то не согласен с этим подходом, то в рамках задачи делает в соотв. с документом, но дальше предлагает изменить документ.
Если вы часто нанимаете и типовым образом погружаете людей в проект, то гайд со схожей структурой у вас образуется сам собой. Я рекомендую исходить из объяснения того, как решается несколько типовых задач. А также дополнительно показать как именно эти соглашения можно менять, можно вовлечь на частном примере или показать историю изменений файла/обсуждения. Уверяю, что это сыграет очень сильную роль в будущем новичка в вашем проекте.
В дальнейшем, первые недели данный документ станет частым местом для CTRL+F новичка в вашем проекте. По моим наблюдениям погружение можно снизить с 2-4 недель до нескольких дней благодаря такому документу (или иному единственному источнику истинны).
Я распишу несколько разделов для ознакомления, оставляя все в виде списков без детализации.
Самый сложный раздел, для каждого проекта полностью специфичен.
Если у вас новый проект на реакте возьмите и сошлитесь здесь на FSD, если angular то строго используйте официальные гайдлайны.
Если старый проект, то приложите сюда граф импортов проекта. Опишите типовые элементы системы, напр. компоненты/страницы/сервисы и для каждого опишите зачем он нужен, как устроен. Опишите структуру директорий. Это минимально.
- https://feature-sliced.design/
- https://ru.hexlet.io/courses/js-frontend-architecture
- https://www.youtube.com/watch?v=VegNqfiS6k8
- Все вне директории legacy должно полностью следовать FSD
- Файлы и директории строго именуем в snake_case
- Любые helpers / utils файлы вне common запрещены
- Как создать типовой UI компонент
- Добавляем новую страницу
- Как сделать свой хук
- Как добавить новый пакет
- Изменение размера бандла, как оценить с новой зависимостью
- Добавление новой зависимости вместе с продуктовым PR запрещено, добавляем отдельным предварительным PR и согласуем с лидом
- Добавление depricated авторами зависимостей запрещено
- Запрещено добавлять дублирующие зависимости
- Новый пакет обязательно должен поставляться в виде es module
При написании react-компонентов мы предпочитаем писать компоненты с помощью функций, а для вынесения частей бизнес кода хуки или чистые функции.
- Пишем сториз для сторибука
- Разметка для трекеров. Аналитика
- Экспорт иконок из Figma
- Добавляем растровые картинки
- Замеряем ререндеры компонента
- Любой новый UI компонент должен содержать сториз
- Запрещен закомментированный код
- Запрещены console.log или любой код для отладки
- Работа с асинхронными операциями используем только async/await
- Распаралеливаем запросы там где это возможно
- Код, кроме реекспорта, в index.ts файлах запрещен
- Запрещено передавать неиспользуемые пропсы
- Запрещены default экспорты
- Бразуерное апи должно вызываться только внутри useLayoutEffect
- Правила eslint запрещено отключать
Мы используем css-modules всегда, глобальные стили запрещены. Используем общие миксины там где это возможно. Мы используем CSS Custom Properties, а все доступные переменные с дизайн-токенами можно посмотреть в локально развернутом сторибуке. Эти переменные доступны глобально: для их использования не нужно ничего импортировать.
- https://andrew-r.ru/notes/bem-vs-css-modules/
- https://ru.bem.info/methodology/css/
- https://css-tricks.com/the-shapes-of-css/
- https://alligator.io/css/currentcolor/
- https://ishadeed.com/article/css-color/
- Какие миксины у нас есть и как их используем
- Добавляем новый миксин
- Разрешен только один файл стилей на директорию
- Запрещена адаптивность посредством media запросов (используем js вместо этого)
- Везде где можно используем дизайн токены
- Корневой элемент всегда именуем root
- Глобальные стили строго запрещены
- Используем currentColor для цвета svg иконок
- Правила stylelint запрещено отключать
Используем redux в связке с redux-toolkit. Само хранилище описано и собирается в /store нашего проекта, есть “общая часть” в /store /general. Бизнес части описываются в слайсах в рамках фич. Общая часть строго не зависит от слайсов.
- Как добавить новый слайс
- перед инициализация нужно обязательно ресетить стейт
- импортировать хранилище разрешено только в страницах и фичах
Сервис - абстракция для работы с данными. Сервисы могут работать с аналитикой, нашим api или предоставлять интерфейс доступа к иным данным (например маппинг роутинга).
Сервис состоит из файла с методами (имя сервиса) и адаптера. Адаптер содержит в себе методы преобразования полученных данных, его наличие обязательно если вы собираетесь как-то изменить полученные с сервера данные перед тем как разместить их в нашем сторе.
Для сервиса который работает с сетью также обязательно наличие мок реализации, это необходимо для корректной работы блоков в сторибуке.
- Разработка сервиса
- Реализуем мок
- Адаптер imgproxy обязателен если в ответе есть url графики
- Наличие мок реализации обязательно
- Правильно реагируем на сетевые ошибки в интерфейсе
- Запрещено заглушать ошибки, интерфейс должен реагировать на них
- Наличие непредсказуемых ошибок в консоли запрещено
- Как ограничить доступ к роуту
- Скрываем виджет или блок в зависимости от ролей
- Добавляем новую роль пользователя
- Как посмотреть страницу с другим набором ролей
- При работе с ролями используем только хук usePermission, напрямую обрабатывать обьект пользователь запрещено
- Как смотреть ошибки в sentry
- Как смотреть логи
- Где смотрим графики и что они значат
- Деплой хотфикса
- Добавляем новый секрет
- Все секреты должны быть в vault
- Какой бывает специфика в разных деплоях
- Брендируем стили
- Добавляем специфичный виджет в тенант
У нас нет локализаций. Тексты размещаются inline.
- в UI компонентах строки запрещены, все текста передаются пропсами
Мы стремимся делать интерфейс доступным. A11y. Цели покрывать весь интерфейс доступностью - нет, но базовые вещи уже нужно начинать делать. Например следует использовать семантические HTML-элементы там, где возможно.
- https://www.sberbank.ru/ru/person/specialbank/digitalguide
- https://a11yproject.com/
- https://a11y-style-guide.com/style-guide/
- https://www.sarasoueidan.com/blog/keyboard-friendlier-article-listings/
- https://www.youtube.com/watch?v=KAK-WAb9vow
- https://www.24a11y.com/2018/accessible-svg-icons-with-inline-sprites/
- https://www.w3schools.com/html/html5_semantic_elements.asp
- https://www.freecodecamp.org/news/semantic-html5-elements/
- https://cloudfour.com/thinks/autofill-what-web-devs-should-know-but-dont/
- https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete
- Как кастомный компонент сделать на базе нативного аналога
- Как сделать доступную модалку
- aria-label, aria-disabled и tabIndex должны быть размещены по возможности везде где это требуется
- Inline-компоненты (ссылки, лейблы, ...) не должны иметь размер шрифта
- Интерактивные компоненты (инпуты, кнопки, ...) должны иметь стили для :hover, :active, :focus и :disabled
- Интерактивные компоненты (инпуты, кнопки, ...) должны иметь обводку при :focus
- Интерактивные компоненты (инпуты, кнопки, ...) должны иметь cursor: pointer по умолчанию и cursor: defaultв состоянии :disabled.
- SVG-иконки должны быть доступными
- Для подтверждения формы использовать событие onSubmit, для отмены/очистки - использовать событие onReset
- Используем по возможности autoFocus
- Блокируем фокус в рамках модальных окон
- Для кнопок используем , для ссылок
- Прогононяем демостенд в lighthouse
- Внешние ссылки обязаны содержать
rel="noopener noreferrer"
Для раскатки функционала для части пользователей у нас есть два механизма: фичефлаги и AB-тесты.
Примерное правило для выбора между ними: если есть АБ-тест, то разработку следует делать через него. Если АБ- теста нет или он закончился – фичефлаг.
При этом обычно AB-тесты – инструмент аналитиков и продакт-менеджеров/продакт-овнеров, и инициатива разработки через AB-тестирование исходит от них. Фичефлаги используются, например, если требуется выкатить какой-нибудь функционал (или часть функционала) на прод, но чтоб у пользователей не было к нему доступа, или для постепенной выкатки функционала после завершения АБ-теста.
- Разработка с использованием эксперимента
- Заводим флаг в flipper
- Фичефлаг должен иметь префикс вида tckt-XXXX-* и ссылаться на конкретный тикет в jira описывающий поведение флага
- Добавляем data-qa-id
- Пишем e2e тест
- Пишем unit тест
- Новый скриншотный тест
- Обновляем скриншотные тесты
- Если обновлены UI компоненты обязательно обновляем сторишоты