Как и у многих программистов, у меня полно маленьких проектов, которыми я занимаюсь время от времени. Это может быть сайт, библиотека, решение каких-нибудь челленджей, сайд-проект или же просто «hobby project».
Когда таких проектов много, возникает проблема: я возвращаюсь к проекту спустя долгое время и уже забыл большую часть того, что в нём происходит. Код кажется странным, но при попытке исправить всё может сломаться нетривиальным образом. Или даже просто забыл, почему я принял определенное решение.
Чтобы это исправить, я придумал несколько правил для хобби-проектов. [^1] Трюк заключается в том, чтобы документировать самые важные решения, но дьявол, как всегда в деталях.
Когда текст ниже говорит «ты», я обращаюсь не только и не столько к тебе, анонимный читатель, сколько к себе. Я не говорю, что придерживаюсь этих правил всегда, но мне кажется, что это хороший фундамент.
Задокументировать архитектуру в ARCHITECTURE.md
Описание проекта так, как описывал бы коллеге, вручая репозиторий, уезжая в горы на месяц. Главные куски (поименно), как они взаимодействуют, что с ними сейчас, надежды на будущее.
Например, кусок из ARCHITECTURE.md Комлинка:
### Accounts
Контекст, отдельный от всего остального. Не должно быть зависимостей во вне (например, на Feeds).
Этот контекст занимается _пользователями_: регистрация через почту, через гитхаб, подтверждение аккаунтов, инвайты.
### Feeds
Контекст, который занимается _постами_ и комментариями к ним.
### Events
Контекст, который занимается _событиями_: например, конкретная встреча нодскула.
## Веб
### Вьюхи
Для каждой сущности должно в итоге быть несколько шаблонов:
1. Full. Entity with all related things.
E.g. Post: includes Comments, includes Author, includes Group, etc.
2. Widget. When element is tightly related on one-to-one basis
E.g. on Event page there would be Place widget.
3. List item. When we present a list of homogenous entities.
E.g. On main page, we see a list of posts. On post page we see a list of comments.
4. Line. When we mention entity in passing.
Бессовестно написанный на смеси русского и английского — потому что я так думаю. (см. доклад Махоткина: надо меньше стесняться русского языка).
Это не финальная версия, и это не design upfront, как может показаться. По мере разработки улучшается понимание как должно быть, его и стоит документировать. Здесь же можно задокументировать важные моменты, которые почему-то плохо выражаются в коде.
В каком случае правило помогает: когда возвращаешься через месяц-полгода к проекту, становится сильно проще восстановить структуру в голове. Зная структуру, становится проще локализовывать проблемы.
Записать в README.md как запустить проект с нуля
Проект может быть написан на чём угодно. У проекта может быть десяток разных зависимостей и требований к окружению. Никому не нравится брить яка, выясняя детали походу: лучше их просто описать.
В каком случае правило помогает: когда переезжаешь на другой компьютер. Когда нужно настраивать деплоймент. Когда открываешь проект через полгода и думаешь, как запустить.
Покрыть тестами то, что может сломаться
Чтобы не бояться менять то, что можно менять. Не надо целиться на стопроцентное покрытие тестами — но имеет смысл потестировать суть и самые важные флоу. Так что это не про юнит-тесты, а про интеграционные тесты и user acceptance тесты.
В каком случае правило помогает: когда пишут про баг, хочется удостовериться, что ты исправил и не поломал ничего другого. Добавить ещё один тест в настроенное окружение сильно проще, чем настраивать с нуля.
Деплоить одной простой командой
Хуже всего, когда пишут в твиттере, мол, сайт не работает, ты уже пофиксил — а как деплоить-то и забыл. Rsync? А какие флаги нужны? А на каком сервере оно сейчас лежит? (pun intended)
Хотя нет, ещё хуже — это когда процесс деплоймента звучит как «так, делаешь ssh на сервер, ищешь директорию, делаешь git pull, мёржишь конфликты, потом запускаешь вот такую команду…» У тебя и так много боли, не надо добавлять её ещё и деплойментом.
В каком случае правило помогает: Каждый. Чёртов. Раз.
Задокументировать создание серверов
Даже если в моменте кажется «да там дроплет создал, хуё-моё, постгрес накатил и скачал архивчик, делов-то», лучше описать процесс, пока можешь. Рано или поздно с сервером что-то случится, и, по законам Мёрфи, в этот момент уже будет поздно вспоминать.
Стоит описывать дистрибутив, пакеты, команды, как настроить сервис, надо ли делать что-то для persistence.
Если в проекте используется несколько серверов (например, сервер для сборки, или вынесена база данных на отдельный сервис) — описывать все, и описывать, как они узнают друг о друге.
В каком случае правило помогает: Когда по каким-то причинам Облако превратилось в чужой компьютер, который не работает.
Вести роадмап вне головы и ввести цели
Иногда идеи насчёт проекта приходят тогда, когда занимаешься чем-то совершенно другим. Запомнить не получится, бросать одно дело ради другого не масштабируется — лучше просто записать, а когда дело дойдёт до этого проекта, тогда и достать все записанные идеи. Заодно к этому времени будет меньше эмоциональной привязанности к идее и будет понятно, насколько она дурацкая. Больше половины идей — дурацкие.
Роадмап на пару шагов вперёд помогает удерживать big picture в фокусе. Цели проекта помогут оценить, правильно ли идёт дело.
В каком случае помогает: Когда хобби-проект начинает расти.
[^1]: На самом деле эти правила применимы и к нормальным проектам, но об этом в другой раз.