Код плохо документирован? Вполне вероятно, что проблема не в программистах, а в том, как построена работа в компании.
Достаточно сложно найти и привлечь в свою команду высококлассных разработчиков. А вот приобретение таких сотрудников, которые умеют хорошо документировать код, — это, на первый взгляд, не проблема.
Давайте пока абстрагируемся от пользовательской документации. Мануалы, справочные руководства и онлайновая документация — это тексты, создание которых лучше оставить техническим писателям. Ведь специализация техписов — излагать доступным языком технические спецификации. Такая документация пишется уже для готового продукта. Однако в процессе разработки программы очень важно вести подробную документацию для внутреннего использования.
В команде разработчиков всегда присутствует текучка — в бизнесе это нормально. Программист может поменять работу, перейти из одного отдела в другой либо вообще уйти из айтишной сферы. Не исключены и совсем мрачные обороты — тяжелая болезнь, инвалидность или смерть. Все эти факторы могут резко ограничить возможности команды в самый неподходящий момент. Код также стареет; программист вполне может забыть, как работает его собственный код, если не занимался им на протяжении года или дольше.
Во всех описанных сценариях важнейшую роль играют проектировочная документация, спецификации API, мануалы и даже комментарии в коде. Именно от этой информации зависит, что мы имеем на выходе — готовый продукт или заваленные сроки. К сожалению, очень немногие разработчики умеют качественно документировать свой код. Воспитание такой привычки может оказаться сложной, но вполне решаемой задачей.
Почему программисты не пишут документацию?
Существует много причин, по которым разработчики не документируют свой код. Некоторые их них проще устранить, чем другие.
Распространен стереотип: дескать, разработчик не документирует код из чистого упрямства. «Настоящие программисты документацию не пишут» — это старинный пережиток хакерского бахвальства, который многие кодеры, к сожалению, воспринимают слишком буквально. Встречаются и такие программисты, которые намеренно не документируют и даже специально запутывают свой код, чтобы казаться «незаменимыми» или «повышать свой авторитет в компании».
Такое отношение к работе разрушительно и неприемлемо. Но примеры подобного непрофессионализма встречаются реже, чем может показаться. В абсолютном большинстве случаев разработчики не документируют код по гораздо более прозаическим причинам.
Во-первых, когда именно программист должен документировать код? Общеизвестно, что программные модули зачастую пишутся, а потом многократно переписываются перед релизом, но могут дописываться и позже. Если разработчик слишком рано начнет документировать реализации API, то он как будто подписывается под проектными решениями, которые являются лишь гипотетическими. Более того, если позже спецификация или требования изменятся, но никто не вспомнит, что и мануал нужно переписать, то возникнет неточная и устаревшая документация. Такой исход еще хуже, чем полное ее отсутствие. Эти проблемы только усугубляются в контексте современных методологий «гибкого» программирования, где делается упор на сверхбыстрое создание готового кода и итеративную разработку.
Еще один вопрос — сколько времени программист должен тратить на написание документации? В большинстве компаний основные обязанности разработчика заключаются в проектировании, реализации, отладке и поддержке кода. Но если результативность программиста оценивается прежде всего по выполнению этих основных задач, он, скорее всего, будет заниматься остальной (менее существенной) работой в последнюю очередь, особенно если в организации слишком много внимания уделяется нормам производительности, которые берутся с потолка. Скорее всего, документирование кода будет восприниматься как «несущественная работа».
Сколько нужно документации?
Правда, все не так плохо. Все проблемы, перечисленные выше — управленческого характера, а значит, они могут быть решены путем оптимизации менеджмента. Но необходимо сознавать, что любые инициативы по улучшению документирования кода должны исходить сверху вниз. Если менеджер не назовет документацию в числе основных приоритетов, разработчики не будут ею заниматься. В данном случае задачи менеджера не сводятся к выдаче разнарядок или к критике существующих подходов к работе. Если менеджеру требуется хорошая документация, он должен предоставить разработчикам возможность ее написать.
Пожалуй, самое важное, что может сделать айтишный менеджер для стимулирования работы по документированию — четко объяснить, какая именно документация ему требуется. Разработчики часто начинают противиться, если их требуют так подробно прокомментировать код, чтобы даже непрофессионал мог шаг за шагом его прочитать. И они правы!
Споры о том, следует или не следует комментировать код, стары как само программирование. С одной стороны, таинственные хитросплетения кода могут быть непостижимы для новичков, если код лишен всяческих аннотаций. С другой стороны, построчное комментирование простейших структур в коде («здесь начинается цикл») — абсолютно бессмысленное занятие. Читать такой код будет только сложнее. Устаревшие или невразумительные комментарии («не трогайте эту переменную!») не менее порочны, чем неаккуратная документация API.
Кроме того, традиционные разновидности подробной документации для разработчиков теряют популярность — особенно в тех организациях, где практикуется гибкая разработка. Общеизвестно, что подсчет строк кода — плохой способ измерения производительности программиста. Аналогично количество строк или страниц подготовленной документации не всегда коррелирует с ее ценностью.
В данном случае действует всего одно железное правило: разработчики должны писать «хорошую» документацию. И все. Если документация достаточно качественная для выполнения поставленных задач — то она хороша. Любой дополнительный текст, вероятно, будет излишним. Конечно, звучит расплывчато, но здесь действительно сложно сформулировать какие-то правила; разработчики должны сами уметь определять, какая документация является хорошей.
Приемы улучшения документации
На развитие культуры написания документации требуется время. Поддержка этой культуры требует постоянного стимулирования. Менеджер должен пользоваться скорее пряником, чем кнутом. Программисты — самые обычные люди, они предпочитают стимулы, а не приказы. Обычная похвала позволяет добиться очень многого, но менеджеры могут изобретать и другие способы вознаграждения разработчиков. Вам ведь случается иногда вызванивать программиста и нагружать его поддержкой программы на выходные или развертыванием обновлений среди ночи? Если программист не поленится еще и написать документацию — дайте ему заслуженную передышку. Разумеется, финансовые стимулы работают не хуже.
Уже многие годы в различных методологиях программирования развиваются идеи о том, что документация кода должна стать более естественной и автоматической. Наиболее ярким проявлением такого подхода является концепция «грамотного программирования», предложенная Дональдом Кнутом. Согласно этой теории, синтаксис алгоритмов должен приближаться к синтаксису естественного человеческого языка. Более практичным подходом, применяемым во многих организациях, является «самодокументирование кода». В данном случае программисты должны придерживаться определенных стандартов именования и структурирования кода. В результате код становится более однородным и легким для восприятия.
Однако наиболее эффективный способ приучить разработчиков к документированию кода — это командный подход к написанию документации. Если группа программистов отвечает за разработку нескольких модулей кода, предложите им сделать презентацию для всей команды и объяснить, как работает их код. В процессе подготовки такой презентации они выполнят большую часть рутинной работы по подготовке формализованной документации, а те вопросы, которые возникнут в ходе презентации, помогут прояснить оставшиеся неоднозначности.
Еще один удобный прием — парное документирование. Фактически здесь процесс документирования строится по принципам гибкой разработки. Если документирование кода — не изолированный вид деятельности, а существенная часть осуществления общекомандных целей, то эта работа воспринимается как менее обременительная и становится естественной частью повседневного труда.
Через все вышесказанное красной нитью проходит еще один тезис: документирование кода никогда не является пассивным процессом. Слишком распространено мнение о том, что документирование может происходить автоматически, а когда такой информации в наличии не оказывается — начинаются жалобы. К сожалению, документирование кода — одна из таких задач, которые не следует решать задним числом. Приступайте к написанию документации уже сегодня. Если же наладить такую работу в компании не удается, то, скорее всего, дело не в разработчиках, а в неверно построенных бизнес-процессах.
Нейл Мак-Аллистер
Источник
Релоцировались? Теперь вы можете комментировать без верификации аккаунта.