Документируйте всё!

Документируйте всё!

duverse

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

В чем дело?

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

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

В своей работе, за которую я получаю зарплату, я часто сталкивался с такими дилентантами вроде меня. Ох... нехватало слов как я ненавидел их лидов, и незаметил как стал одним из них.

Никто не любит писать документацию. Но порой, даже самому автору такие вещи приносят пользу.

Давайте мыслить трезво. Один репозиторий проекта "UserHUD" (кодовое название), содержит несколько десятков инструментов. Это своего рода toolkit toolkit'ов для разработки поднобного проекта и тесная интеграция с отдельными микросервисами. При должном подходе - каждая из утилит должна была бы быть вынесена в отдельный репозиторий. Но, пока, это не нарушает целостности и модульности проекта, хотя и появляются неприятные последствия (вроде ненужных зависимостей в определенных местах).

Лишь один инструмент - view_wizard для django содержит столько уже реализованного функционала, что я сперва пишу так, как это привык делать на рабочих проектах, и лишь потом вспоминаю что количество написанного кода можно уменьшить в несколько раз. Дошло до того, что я начинаю медленно но увернно внедрять свои утилиты в рабочие проекты (а там только рады что, казалось бы, огромные задачи решены в считанные минуты). Таким образом я пытаюсь поддерживать свежесть привычек использовать свои инструменты правильно.

Так не должно быть! Нужна документация. Когда дело дойдет до разработки UX-логики, документация позволит мне сэкономить драгоценное время. А ведь для фронтэнда, да-да, у меня на бэкэнде создана целая "секта" плюшек которые тесно взаимодействуют с UI, ускоряют мою работу в разы, при этом позволяя получать максимально стабильный код. Например, у объекта window каждой страницы сайта, есть переменная окружения. Она передается вместе с html-кодом при загрузке страницы. Это позволяет сэкономить количество XHR-запросов к хосту сайта, тем самым снизив расходы, трафик и повысив скорость загрузки. И да, я понимаю все последствия содеянного в области безопасности. Потому все данные хранящиеся так открыто - не несут никакой ценности.

Вывод

Как минимум README!