Как приучить разработчиков документировать свой код

8 комментариев
Как приучить разработчиков документировать свой код

Код плохо документирован? Вполне вероятно, что проблема не в программистах, а в том, как построена работа в компании.

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

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

Почему программисты не документируют код, сколько документации нужно и как лучше ее делать

В команде разработчиков всегда присутствует текучка — в бизнесе это нормально. Программист может поменять работу, перейти из одного отдела в другой либо вообще уйти из айтишной сферы. Не исключены и совсем мрачные обороты — тяжелая болезнь, инвалидность или смерть. Все эти факторы могут резко ограничить возможности команды в самый неподходящий момент. Код также стареет; программист вполне может забыть, как работает его собственный код, если не занимался им на протяжении года или дольше.

Во всех описанных сценариях важнейшую роль играют проектировочная документация, спецификации API, мануалы и даже комментарии в коде. Именно от этой информации зависит, что мы имеем на выходе — готовый продукт или заваленные сроки. К сожалению, очень немногие разработчики умеют качественно документировать свой код. Воспитание такой привычки может оказаться сложной, но вполне решаемой задачей. 

Почему программисты не пишут документацию?

Существует много причин, по которым разработчики не документируют свой код. Некоторые их них проще устранить, чем другие. 

Распространен стереотип: дескать, разработчик не документирует код из чистого упрямства. «Настоящие программисты документацию не пишут» — это старинный пережиток хакерского бахвальства, который многие кодеры, к сожалению, воспринимают слишком буквально. Встречаются и такие программисты, которые намеренно не документируют и даже специально запутывают свой код, чтобы казаться «незаменимыми» или «повышать свой авторитет в компании».

Такое отношение к работе разрушительно и неприемлемо. Но примеры подобного непрофессионализма встречаются реже, чем может показаться. В абсолютном большинстве случаев разработчики не документируют код по гораздо более прозаическим причинам.

Во-первых, когда именно программист должен документировать код? Общеизвестно, что программные модули зачастую пишутся, а потом многократно переписываются перед релизом, но могут дописываться и позже. Если разработчик слишком рано начнет документировать реализации API, то он как будто подписывается под проектными решениями, которые являются лишь гипотетическими. Более того, если позже спецификация или требования изменятся, но никто не вспомнит, что и мануал нужно переписать, то возникнет неточная и устаревшая документация. Такой исход еще хуже, чем полное ее отсутствие. Эти проблемы только усугубляются в контексте современных методологий «гибкого» программирования, где делается упор на сверхбыстрое создание готового кода и итеративную разработку.

Еще один вопрос — сколько времени программист должен тратить на написание документации? В большинстве компаний основные обязанности разработчика заключаются в проектировании, реализации, отладке и поддержке кода. Но если результативность программиста оценивается прежде всего по выполнению этих основных задач, он, скорее всего, будет заниматься остальной (менее существенной) работой в последнюю очередь, особенно если в организации слишком много внимания уделяется нормам производительности, которые берутся с потолка. Скорее всего, документирование кода будет восприниматься как «несущественная работа».

Сколько нужно документации?

Правда, все не так плохо. Все проблемы, перечисленные выше — управленческого характера, а значит, они могут быть решены путем оптимизации менеджмента. Но необходимо сознавать, что любые инициативы по улучшению документирования кода должны исходить сверху вниз. Если менеджер не назовет документацию в числе основных приоритетов, разработчики не будут ею заниматься. В данном случае задачи менеджера не сводятся к выдаче разнарядок или к критике существующих подходов к работе. Если менеджеру требуется хорошая документация, он должен предоставить разработчикам возможность ее написать.  
Пожалуй, самое важное, что может сделать айтишный менеджер для стимулирования работы по документированию — четко объяснить, какая именно документация ему требуется. Разработчики часто начинают противиться, если их требуют так подробно прокомментировать код, чтобы даже непрофессионал мог шаг за шагом его прочитать. И они правы!

Споры о том, следует или не следует комментировать код, стары как само программирование. С одной стороны, таинственные хитросплетения кода могут быть непостижимы для новичков, если код лишен всяческих аннотаций. С другой стороны, построчное комментирование простейших структур в коде («здесь начинается цикл») — абсолютно бессмысленное занятие. Читать такой код будет только сложнее. Устаревшие или невразумительные комментарии («не трогайте эту переменную!») не менее порочны, чем неаккуратная документация API.

Кроме того, традиционные разновидности подробной документации для разработчиков теряют популярность — особенно в тех организациях, где практикуется гибкая разработка. Общеизвестно, что подсчет строк кода — плохой способ измерения производительности программиста. Аналогично количество строк или страниц подготовленной документации не всегда коррелирует с ее ценностью.

В данном случае действует всего одно железное правило: разработчики должны писать «хорошую» документацию. И все. Если документация достаточно качественная для выполнения поставленных задач — то она хороша. Любой дополнительный текст, вероятно, будет излишним. Конечно, звучит расплывчато, но здесь действительно сложно сформулировать какие-то правила; разработчики должны сами уметь определять, какая документация является хорошей.

Приемы улучшения документации

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

Уже многие годы в различных методологиях программирования развиваются идеи о том, что документация кода должна стать более естественной и автоматической. Наиболее ярким проявлением такого подхода является концепция «грамотного программирования», предложенная Дональдом Кнутом. Согласно этой теории, синтаксис алгоритмов должен приближаться к синтаксису естественного человеческого языка. Более практичным подходом, применяемым во многих организациях, является «самодокументирование кода». В данном случае программисты должны придерживаться определенных стандартов именования и структурирования кода. В результате код становится более однородным и легким для восприятия.  

Однако наиболее эффективный способ приучить разработчиков к документированию кода — это командный подход к написанию документации. Если группа программистов отвечает за разработку нескольких модулей кода, предложите им сделать презентацию для всей команды и объяснить, как работает их код. В процессе подготовки такой презентации они выполнят большую часть рутинной работы по подготовке формализованной документации, а те вопросы, которые возникнут в ходе презентации, помогут прояснить оставшиеся неоднозначности.

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

Через все вышесказанное красной нитью проходит еще один тезис: документирование кода никогда не является пассивным процессом. Слишком распространено мнение о том, что документирование может происходить автоматически, а когда такой информации в наличии не оказывается — начинаются жалобы. К сожалению, документирование кода — одна из таких задач, которые не следует решать задним числом. Приступайте к написанию документации уже сегодня. Если же наладить такую работу в компании не удается, то, скорее всего, дело не в разработчиках, а в неверно построенных бизнес-процессах.

Нейл Мак-Аллистер  

Источник

Хотите сообщить важную новость?

Пишите в наш Телеграм

Читайте также

Как защитить видеозвонки. Советы экспертов
Как защитить видеозвонки. Советы экспертов

Как защитить видеозвонки. Советы экспертов

За месяц число ежедневных активных пользователей сервиса для видеосвязи Zoom выросло в 1,5 раза — с 200 млн до 300 млн, хотя ещё в декабре их было лишь 10 млн. По мере роста популярности приложение стало привлекать хакеров, а в сети появилось столько новостей об уязвимостях Zoom, что на мессенджер обратило внимание ФБР. Издание Computerworld собрало небольшой список рекомендаций от экспертов по кибербезопасности о том, как защитить данные и участников видеоконференций от взломов, утечек и непрошенных гостей.
Guardian: массовые мероприятия как топливо для эпидемии
Guardian: массовые мероприятия как топливо для эпидемии

Guardian: массовые мероприятия как топливо для эпидемии

Коллективная статья семи журналистов Guardian о том, почему массовые скопления, рукопожатия, поцелуи и общие напитки виноваты в распространении коронавируса. Публикуем перевод материала с незначительными сокращениями.
1 комментарий
10 образовательных приложений, чтобы провести самоизоляцию с пользой
10 образовательных приложений, чтобы провести самоизоляцию с пользой

10 образовательных приложений, чтобы провести самоизоляцию с пользой

Перевели подборку бесплатных приложений для удалённого обучения. для тех, кто устал от доомашнего спорта, документалок и сериалов.
3 комментария
Как локдаун помог интернету
Как локдаун помог интернету

Как локдаун помог интернету

MIT Technology Review объяснили, почему резкий рост трафика не «сломал» сеть, а привёл к серьёзным качественным улучшениям.

Обсуждение

3

Краткое содержание статьи: "Документация это хорошо. Программисты любят программировать и не очень любят писать документацию. Нужно найти способ "пряника", который убедит программистов писать документацию. Давайте заставим их писать документацию парами (это видимо, чтобы видели, что не только они мучаются, но и напарник) и поставим им в обязанность готовить по своей документации еще и презентации!"

1

Хороший программист хочет писать документацию, но ему в этот момент нужно быть на скрам митинге. Утрирую, но в каждой шутке...
Приходится подсовывать это под видом TDD вмещая сюда документацию, дизайн и тестирование. Тесты и api doc становятся единственными инструментами для документирования. У тестов меньше проблем с устареванием, так как в случае неактуальности они падают.

-1

Всё начинается с ТЗ.
Если нет грамотного и полного ТЗ, то код будет многократно переписываться перед релизом и тестировщики будут тестировать незнамо что и т.д. и т.п. Если нет ТЗ, если всё показывалось и объяснялось на пальцах, то и коду документация не нужна, ведь какой в ней смысл, если через полгода никто помнить не будет что и как вообще должно делать приложение, не говоря уж об отдельном блоке или методе.
Если есть ТЗ, то ИМХО достаточно в код, в соответствующие места, просто скопипастить текст из ТЗ (типа "расчёт себестоимости продукта по следующему алгоритму..."). Комментировать синтаксис смысла нет ибо если в код пускают новичка, не умеющего свободно прочесть даже это, значит проект не того уровня, что бы заслуживать дополнительных затрат на документирование.

1

Не, ну копипастить я бы не стал...

В моей голове все выглядит примерно так.
Есть задача. Она описана в спецификации в терминах сравнительно человеческих. По этой спеке пишется код. Чем ближе идейно (очень хочется вставить слово "семантически") код приближен к спеке - тем лучше. Если встречается сложный момент, который хочется прокомментировать, прежде всего следует задуматься - а не переписать ли его в более понятном "стиле".

Будучи приверженцем написания самодокументирующегося кода, не соглашусь с вот этой фразой из статьи:
>> Более практичным подходом, применяемым во многих организациях, является «самодокументирование кода». В данном случае, программисты должны придерживаться определенных стандартов именования и структурирования кода. В результате код становится более однородным и легким для восприятия.

Стандарты именования - они ведь достаточно условны. Например, меня уже давно не коробят "неправильно" расставленные фигурные скобочки. Для меня важна ясность изложения "мыслей", выраженных в коде. Начиная от понятных названий свойств и методов, заканчивая визуальным оформлением кода для облегчения восприятия - пустые строки, смысловая группировка операторов и переменных и т.п.

Это просто привычки, которые должны быть "выращены" самостоятельно. Мне кажется, административно тут делу не поможешь. Хотя, если стегать проводом от мышки...

0

Действительно. Я сейчас тестирую этот подход: хочется написать комментарий - делай рефакторинг, пока комментарий не станет дублирующим (extractUserNameFromArray(array); // Извлечь имя пользователя из массива). Но это требует больших усилий (по крайней мере пока), т.к. простой код писать сложно. И да, от документирования интерфейса никуда не деться. Но потом самому даже приятно смотреть на такой код. Все как на ладони.

0

Да, код, написанный "человеческим" языком - это круто. Иногда открывал исходники с таким кодом и реально любовался, как книжку читал )

0

< Стандарты именования - они ведь достаточно условны. Например, меня уже давно не коробят "неправильно" расставленные фигурные скобочки. Для меня важна ясность изложения "мыслей", выраженных в коде. >
Согласен. 100% следование стандарту кодирования не так важно, хотя бы потому, что редко когда вся программа будет написана в соответствии с ним (по крайней мере, у меня такой опыт). Гораздо важней "интуитивная понятность" кода - а это достигается именно тем, что вы описали - "Начиная от понятных названий свойств и методов, заканчивая визуальным оформлением кода для облегчения восприятия - пустые строки, смысловая группировка операторов и переменных и т.п.". Но стандарт кодирования конечно тоже хорошо )

0

Да ладно. Если нет ТЗ - то тем более надо документировать, так хотя бы какой-то шанс будет потом в этом разобраться. Ну разве что есть 100% уверенность, что этот код не будут править. Но насколько это часто бывает в рабочих проектах, чтоб вот вообще ничего потом не правили?

Комментировать синтаксис действительно не надо, надо комментировать более "высокоуровневые" операции и свои идеи. Т.е. чтоб тот, кто будет это читать - быстро въехал в суть данного куска проги. А если надо будет углубиться - чтоб попал уже к синтаксису, который просто можно читать.

И еще кстати полезно вернуться к комментариям через некоторое время (лучше как минимум на следующий день - утро вечера мудреней - или позже). Если что-то кажется недостаточно понятным или наоборот слишком подробным - подправить. Когда пишешь прогу - глаз замыливается - так что эти недочеты не будут заметны сразу.

Спасибо! 

Получать рассылки dev.by про белорусское ИТ

Что-то пошло не так. Попробуйте позже