Когда вы в последний раз сталкивались с качественно документированным кодом?
С кодом, который можно было использовать буквально «из коробки», просто ознакомившись с небольшим README файлом. Но к которому в то же время прилагалась подробная документация, поясняющая каждую строчку: не только то, что она делает, но и почему она была написана именно так, а не иначе.
Давно ли вы встречали такой код? Неделю назад? Месяц? Год?
Лично мне посчастливилось увидеть такой код пару лет назад. И с тех пор я видел немало кода с… довольно грязной документацией.
Но разве можно винить в этом разработчиков?
Большинство из них крутятся как белка в колесе: написание кода, тестирование, релиз и так по кругу. К тому же, результат их труда будет использоваться буквально здесь и сейчас, а вот читать его еще долго никто не будет — разве что, когда придет время добавить новую функцию или что-то обновить.
Логично, что подавляющее число программистов ставят во главу угла написание кода, а не качественной документации. Зачем тратить несколько часов своего времени на создание того, о чем никто не вспомнит еще полгода, а то и больше.
Конечно, они будут делать какие-то пометки и оставлять комментарии. Информация о том, как устроен и что делает код, будет разбросана по файлам README, докладам с конференций, каналам Slack, каким-то внутренним документам и так далее. Иными словами, информация, которую разработчики не сочтут нужным сообщить, окажется просто недоступна.
И в будущем это создаст массу проблем.
Например, при онбординге. Как только в команде появится новичок, разработчикам, которые приложили руку к разработке, придется потратить время на то, чтобы все ему растолковать. Согласитесь, было бы намного проще, если бы документация со всей информацией о коде была бы собрана в одном месте. Особенно было бы особенно актуально для удаленщиков, которым приходится назначать онлайн-встречу буквально по любому вопросу, вместо того, чтобы просто поймать коллегу у кулера или забежать к нему в кабинет.
Еще одна проблема — сопровождение. Ни один разработчик не помнит свой код в деталях спустя месяцы или даже годы после его создания. И когда возникает необходимость внести какие-то изменения в код — даже самые пустяковые — на поиск нужного фрагмента может уйти не один час! С хорошей документацией на поиск искомой строки ушла бы пара минут, не больше.
А если авторы кода и вовсе покинули этот корабль… Поздравляем! Теперь вам придется потратить добрую пару-тройку месяцев, чтобы разобраться в корпоративном легаси и его беспорядочной документации.
Я бы очень хотел сказать, что утрирую и такие случаи — скорее исключение, чем правило, но… нет. Это не так.
Откуда берется некачественная документация
Давление на разработчика — далеко не единственный фактор, отодвигающий создание документации на задний план. В противном случае программисты, работающие в относительно свободном режиме (да, такие существуют) создавали бы шедевры документации. Увы, это не так.
Глубинная причина заключается в том, что документацию изначально воспринимают как задачу второстепенной важности, за которую имеет смысл браться только после того, как настоящая работа — КОДИНГ — уже выполнена.
А еще разработчики любят кодить. Им не нужны дополнительные административные задачи, которые только удлиняют их рабочий день. Даже программисты, не обремененные давлением бизнес-процессов, не хотят тратить время на такую «ерунду».
Примечание для тех, кто говорит «мой код настолько чист, что ему не нужна документация»
Хороший код должен говорить сам за себя. Безусловно, я согласен с этим тезисом! Но ни один код в мире не покажет всю картину целиком. Даже самый чистый.
Почему было принято именно такое архитектурное решение, почему что-то было реализовано, а что-то нет — ответы на эти вопросы не даст ни один код.
Конечно, пресловутый чистый код легко прочитать и понять — в отрыве от контекста. Но, будь он даже самым чистым в мире, вы вряд ли сразу сообразите, каким образом он взаимодействует с другими частями кода, какую роль в проекте он выполняет и как использовать его в контексте.
И это серьезная проблема, учитывая развитие микросервисов, различных языков программирования и фреймворков. В конце концов, эра спагетти-кода прошла.
Иными словами словами, если ваш идеальный код понятен даже пятилетнему ребенку, документированием пренебрегать нельзя. Вам нужно подготовить хоть какой-то документ, объясняющий, почему этот код вообще существует, почему он написан так, а не иначе, почему какие-то моменты не были реализованы, и как этот код взаимодействует с другими частями кода в контексте более широкой архитектуры.
Для этого и существует документация.
Хорошо документированный код уничтожает статус-кво. Он позволяет избежать головной боли с онбордингом, сопровожденим кода и поддержкой легаси.
Хорошая документация упрощает жизнь новичкам, позволяет поддерживать код в актуальном состоянии и без проблем делиться им с товарищами по команде.
Вот если бы написание документации не было таким отвратительным занятием!
Как быстро писать качественную документацию
Главный ключ к достижению этой цели -— непрерывное документирование. Это новая парадигма программирования, которая быстро набирает обороты.
Идея заключается в том, чтобы сделать создание документации частью процесса программирования. Теперь это не административная задача для внеурочного времени. Написали строчку кода — будьте любезны задокументировать ее.
Это может показаться извращением, но не спешите делать выводы. Этот подход гарантирует, что документация будет создана буквально «по горячим следам», когда вы еще держите в голове логику работы кода, а не спустя пару-тройку месяцев, когда понимание уже улетучится. Написание встроенного комментария займет несколько секунд. Если это не ваш путь, просто выносите аннотации в отдельный файл.
Вы ненавидите встроенные комментарии и мое предложение вас возмутило? Не спешите ругаться, позвольте мне кое-что объяснить.
Пока не существует IDE, которая позволяла бы делать примечания в коде, подобно комментариям в Word или программах для просмотра PDF. Однако инструменты, интегрирующиеся с VS Code и IntelliJ и позволяющие создавать такие аннотации, существуют. Например, Swimm, довольно свежая штука. (Нет, мне не «занесли» рекламодатели, хотя у меня была возможность пообщаться с техническим директором этой компании). В будущем планируется интеграция Swimm с другими IDE.
Конечно, хорошая документация — это не только встроенные комментарии. Как правило, должен быть минимум один документ высокого уровня, например, файл README или нечто более сложное.
Файл README пишется быстро, но парадигма непрерывного документирования заставляет разработчиков поддерживать его в актуальном состоянии. Это можно делать путем упоминания строк или цитирования фрагментов кода прямо в документации. Затем, когда код изменится, вы поймете, что тот самый документ высокого уровня пора обновить.
А если вы не хотите постоянно сравнивать свой README с актуальным кодом, не волнуйтесь: такие инструменты, как Swimm, предупреждают пользователя об изменениях даже в том случае, если вы используете IDE не из списка поддерживаемых. Но ничто не помешает вам делать это вручную или реализовать свой способ автоматизации.
Явные ссылки на ваш код в документации также дают еще одно преимущество: вы можете создавать walkthrough кода.
При работе с кодом (даже самым чистым) начинающим разработчикам не всегда бывает понятно, как один фрагмент кода взаимодействует с другим и какова логика взаимодействия разных компонентов. Здесь вам поможет walkthrough. Это что-то наподобие туториала, только не для конечного пользователя, а для разработчика.
Walkthrough — это отдельный документ, в котором можно объяснить, как один фрагмент кода связан с другим, используя ссылки на README или конкретную строку с встроенным комментарием. Это особенно полезно при размещении кода в разных репозиториях и сервисах: например, когда код фронтенда лежит в одном месте, а код бэкенда — в другом. Новые сотрудники быстрее поймут, что происходит, а опытным разработчикам не придется тратить свое драгоценное время на объяснения. К тому же, это все довольно таки забавно писать.
Итак, непрерывное документирование — это практика, предусматривающая создание и обновление всех видов документации прямо в процессе написания кода. Она касается низкоуровневых встроенных комментариев, высокоуровневых документов вроде README, пояснений и всего, что хоть как-то относится к проекту.
Обновление документации облегчается путем прямого цитирования или создания ссылок на фрагменты кода. Такие инструменты как Swimm могут упростить документирование, особенно если речь идет о большом проекте.
Можно подойти к непрерывному документированию иначе. Например, поместить все ссылки в отдельный текстовый файл, добавить проверку документации в качестве обязательного шага к каждому git-коммиту или запланировать ежемесячные проверки документации.
Статус-кво документации — в топку. Сейчас самое время изменить это.
