Правила хобби-проектов

Как и у многих программистов, у меня полно маленьких проектов, которыми я занимаюсь время от времени. Это может быть сайт, библиотека, решение каких-нибудь челленджей, сайд-проект или же просто «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. На самом деле эти правила применимы и к нормальным проектам, но об этом в другой раз. ↩︎