# Внесение изменений

Набор рекомендаций по процессу внесения изменений в исходный код проекта, будь то реализация новой функциональности,
исправление багов или рефакторинг.

Рекомендации представлены в формате [чеклистов](https://en.wikipedia.org/wiki/Checklist), в которых перечислены пункты,
на которые настоятельно стоит обратить внимание.

Все эти процессы тесно связаны и естевственным образом отражаются на [подходе к работе](working-with-vcs.md) с системой
контроля версий.

## Создание новой функциональности

- [ ] проработка предметной области и выделение основных абстракций;

- [ ] написание кода, реализующего эти абстракции;

    Следует предоставлять в модулях _простые_, _понятные_ и _полные_ (_симметричные_) интерфейсы.

    Огромное количество полезных рекомендаций приведено в [соответствующем документе](code-style.md).

- [ ] покрытие написанного кода спеками;

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

- [ ] покрытие написанного кода тестами;

    Большее внимание стоит уделять тестам, затрагивающим исключительные, неуспешные или ошибочные сценарии
    использования нового функционала, и только потом – тестам успешных или штатных сценариев использования.
    
    Тесты должны быть _самодостаточными_, иными словами явно поддерживать настройку критичного для тестовых сценариев
    окружения, [_mocking_](https://en.wikipedia.org/wiki/Mock_object) или работу с эфемерными внешними зависимостями,
    будь то девственно чистые базы данных, пустые списки и правила контроля доступа или отсутствующие сервера доменных
    имён. В экстремальных случаях возможно даже отсутствие интернета на время запуска и прогона тестов.
    
    Необходимо отказаться в тестах от стохастического поведения, привнесения элемента случайности. Также не стоит
    использовать слишком большие, ничем не оправданные задержки. Каждая операция в тестовом сценарии должна иметь
    понятный и чётко определённый критерий завершения.
    
    Сценарии, опять же _по возможности_, должны быть написаны с расчётом на то, что они будут запускаться в
    экстремальном случае в параллельном режиме, одновременно и в случайном порядке.
    
    Если инструменты для тестирования дают такую возможность, следует давать тестам понятные разработчику названия
    и/или описания.

- [ ] написание документации;

    Если вносимое изменение каким-либо образом отражается на внешних интерфейсах сервиса, приложения или библиотеки
    (при решении бизнес-задач случается в 95% случаев), этот эффект должен быть отражён в документации.
    
    Если реализация задачи привела к появлению нового, отдельного сервиса, хорошей мыслью будет сразу написать к нему
    краткую операционную документацию. Вопросы, которые непременно будут волновать админов / операторов: установка,
    начальная настройка, запуск, проверка работоспособности и конечно же _остановка_.
    
    Чем ближе документация к репозиторию с кодом, тем лучше.

- [ ] подготовка процессов миграции.

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

## Правка багов

- [ ] анализ ситуации, в которой наблюдается ошибочное поведение;

- [ ] написание одного или нескольких тестовых сценариев, покрывающих эти ситуации;

    Хорошим тоном будет сразу провести прогон тестов и проверить, что новые тестовые сценарии действительно
    завершаются неуспешно в отсутствии исправления.

- [ ] исправление логики в исходном коде.

    После этого все тестовые сценарии из предыдущего пункта должны завершатся успешно.
    
    Если в процессе исправления назревает необходимость в рефакторинге, рекомендуется его проводить в рамках
    отдельного процесса внесения изменений.

## Напоминания в коде (TODO, FIXME, etc. )

- [ ] исправлены все `BUG`, `TODO`, `FIXME` и др., которые могут и должны быть решены в рамках текущей задачи

- [ ] все остальные требования действий проассоциированы с задачей/другим позывом к действию

    Следующая запись наверняка добавит ещё один TODO к списку тех, которые никогда не разрешатся, и (что ещё хуже) не даёт возможности понять, актуально ли ещё это:
    ```
    %% TODO: fix this as soon as we deploy FooBar feature
    ```
    
    Следующая же запись позволит (даже автоматизированно) проверить актуальность задачи и возможность приступить к ней:
    ```
    %% TODO(ED-1234): fix this as soon as we deploy FooBar feature (ED-999)
    ```

- [ ] другие заметки на тему производительности и других не критичных с точки зрения бизнес-логики вещей помечены тэгом без позыва к действию: `HACK`, `NOTE`, `PERF`, `KLUDGE`, `XXX`.