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

Документирование кодовой базы. Зачем и как?

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

Дисклеймер

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

Начало статьи — это мотивационная часть. Если вы достаточно мотивированы писать документацию — можете смело переходить к пункту «Как?». Хотя я рекомендую почитать и «Зачем?», чтобы мотивировать своих коллег на документирование кода было легче.

Так как я С++ разработчик, то и документирование кода я рассматриваю как документирование кода С++. Когда я говорю код, функция, метод или класс, я подразумеваю код, функцию, метод или класс на С++.

Далее я буду употреблять слова «документация» и «комментарии» в одном смысле — документирование кода внутри кода. Хотя, конечно, документацию и комментарии стоит различать.

Зачем?

Здесь я приведу пару пунктов формата вопрос-ответ. Это те вопросы, которые я задавал себе сам и слышал от своих коллег, когда вставал вопрос документирования кода.

1. «Все и так знают наш код»
   Это утверждение справедливо для разработчиков с большим опытом работы в компании, но никак не для тех, кто только включается в проект. Чем больше документации встретит новичок в коде, тем быстрее он сможет включиться в работу. 10 минут чтения документации лучше, чем 2 часа отладки кода.
2. «Этот код прост и не нуждается в документации»
   Если такая мысль пришла вам в голову, обдумайте ее еще раз. Если подумать еще не помогло, посоветуйтесь со своими коллегами. Если ваш код не вызвал вопросов при одном только взгляде на него, то, возможно, комментирование кода действительно излишне (но это не точно). Этот пункт будет подробнее обсуждаться далее.
3. «Этим кодом больше никто пользоваться не будет»
   Это неправда. Не использоваться он будет до поры до времени. В моей практике были моменты, когда я реализовывал то, что уже есть в нашей кодовой базе. Отсутствие документации и, соответственно, привычки искать существующие решения в ней, привели меня к дубликации кода.
4. «Документация в коде захламляет код»
   Да, это безусловно минус. Читать интерфейс класса становится сложней, чрезмерно большое количество комментариев в блоках кода создает шум. Однако, если будут соблюдаться рекомендации, это даст один большой плюс — программисту не нужно будет лезть в отдельное место и искать описание данного метода/класса/структуры/чего угодно. Описание кода находится в самом коде. А чтобы не захламлять интерфейсы класса, документацию к методам можно выносить в файл с реализацией, а в блоках кода установить ограничение на количество строк/слов в комментарии.Я считаю, что в перспективе это гораздо выгодней и удобней, чем не вести документацию или вести ее в отдельном месте. Посмотрите на документацию библиотеки STL (возможно не лучший пример) — в большинстве случаев, мне не нужно открывать cppreference, чтобы прочитать описание методов. В дальнейшем, из документации в коде, можно автоматически создать готовую документацию с помощью генераторов.

Главный ответ на вопрос «Зачем?» — сделать свою жизнь и жизнь своих коллег проще. Избавьтесь от изучения кода там, где этого можно избежать, от «путешествия» по коду, с целью понять, что делает этот код, за что он отвечает. Покажите своим коллегам, что документация — это экономия большого количества времени. Подумайте о новых сотрудниках, которые могут в разы быстрее включиться в проект.

Понятно, что избавиться от изучения кода полностью невозможно: если вы заняты рефакторингом, исправлением багов или оптимизацией — вы в любом случае будете вынуждены изучать код. Но это и не цель документирования. Цель — свести эту потребность к минимуму, предоставить удобные инструменты для быстрого изучения кода и сэкономить время.

Общие советы документирования

Далее я приведу несколько советов, которые я нашел полезными. Если некоторые из них покажутся вам очевидными — замечательно! (вспомните дисклеймер)

1. Обязательно документируйте то, что кажется вам нетривиальным
   Если решение трудно понять при первом его прочтении — решение нуждается в комментариях. Количество документации для такого кода пропорционально зависит от сложности кода.
2. Приведите пример использования вашего кода
   Оставьте названия функций/методов/классов, ткните в место, где используется ваш код. Если вы использовали какое-то популярное решение (паттерн), оставьте ссылку на материал по этой теме. Это поможет быстрее сориентироваться в коде. Понятно, что поиск в IDE даст вам ту же информацию, но иногда он бывает долгий, плюс таким образом вы сможете особенно выделить то место, где использование вашего кода продемонстрировано максимально явно.
3. Если решение нетривиально, расскажите о причинах такого решения
   Почему использовано именно такое решение? Порой приходится много времени заниматься отладкой и изучением кода, чтобы понять, почему коллега выбрал именно такой подход. Краткий ответ на вопросы зачем и почему сэкономит много времени. Данный пункт переплетается с первым.
4. Постарайтесь найти середину между отсутствием документации и документированием каждой строки
   Не нужно писать целую поэму для метода, из названия которого понятно, что он делает (я надеюсь, что название соответствует тому, что он делает). Также не стоит думать, что, например, простой класс не нуждается в подробной документации. Здесь важно найти золотую середину.
5. Не пересказывайте код
   Не превращайте ваши комментарии в это
6. Не забывайте о поддержке документации IDE
   Сейчас почти все IDE способны выводить описание класса/метода/функции при взаимодействии с ним (наведение мыши, комбинация клавиш), если описание оформлено в нужном формате. Пишите документацию так, чтобы (1) IDE смогла ее «подхватить», (2) можно было обойтись чтением документации и избежать необходимости открывать код с целью его изучения.
7. Дайте описание поведения вашей функции/метода в случае ошибки
   Что вернет ваш код? Возможны ли исключения и какие? Если функция бросает слишком много исключений, возможно не стоит перечислять их все.
8. Помните о том, что ваши комментарии в будущем будут читать другие люди, в том числе и вы
   Не пишите документацию ради документации, пишите ее ради облегчения работы своей команды. Задайте себе вопрос: пойму ли я, что делает этот код, через месяц, посмотреть на комментарии? Для более честного ответа, попросите ответить на этот вопрос своих коллег.
9. Не забывайте об актуальности документации
   Неактуальная информация уже неактуальна хуже ее отсутствия.

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

Как?

Далее речь пойдет о стиле документирования и инструментах. Я считаю, что стиль документирования сродни код-стайлу — он также важен и его также нужно регламентировать (чем подробнее и логичнее, тем лучше). Какой стиль выбрать — зависит уже от вас и вашей команды. Этот раздел статьи — одно из видений стиля, который можно использовать.

Документирование можно вести в стандарте JavaDoc. Это удобный формат, который знаком многим IDE и поддерживается Doxygenом. Плюсом для нас было то, что он уже частично используется в нашем проекте, и IDE, в которых мы работаем (CLion, QtCreator, VisualStudio) прямо поддерживают генерацию комментариев в этом стандарте и их отображение.

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

Далее будут описаны инструменты документации и некоторые правила, которые мы приняли в своей команде.

Многострочные и однострочные комментарии

Doxygen поддерживает много видов комментариев. Для нашей команды я выделил такие:

/** * . Многострочный комментарий . * . вторая строчка многострочного комментария . */ /// Однострочный комментарий Или /* Еще один однострочный комментарий */

Хочу обратить внимание, что

/// . первая строка . /// . вторая строка . 

/** . первая строка . . вторая строка . */

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

Также существует такой вид комментария:

Такой вариант удобен, когда нужно задокументировать одну строку внутри функции, или дать описание переменной или члену класса/метода. Обратите внимание, что между слэшем и стрелкой нет пробела.

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

Команды

В JavaDoc есть так называемые команды. Команды служат для детализации, выделения документации. Команд в JavaDoc довольно много, плюс можно вводить свои. Те команды, которые используем мы, я опишу далее. К сожалению, многие команды (почти все) в C++ не поддерживаются так, как хотелось бы (так, как это сделано в Java). Но тем не менее это отличный способ структурировать вашу документацию, обеспечить удобство при чтении и поддержку Doxygen. Я настоятельно рекомендую пользоваться командами.

Классы, структуры, перечисления, области видимости

Документация должна находиться строго до объявления/описания кода. Это позволит нашим IDE, и в дальнейшем Doxygenу, подхватить комментарии.

Мы документируем такой код многострочным комментарием, даже если описание влезает в одну строку.

/** * Документация для класса example */ class Example < . >;

Это позволяет комментариям не выбиваться из общего стиля документирования. Комментарии в одну строку блочного кода должны быть редкостью!

Для указания краткого описания может быть использована команда @brief. Указанный после команды текст, вплоть до конца параграфа, будет относиться к краткому описанию, и для отделения от основного используется пустая строка.

/** * @brief Краткое описание и * его продолжение. * * Подробное описание */

Насколько такая команда полезна — решать вам.

Также можно (и даже нужно) добавлять команду @example. Такой вариант позволит быстрее найти пример использования кода.

/** * Документация для класса example * @example path/to/file/file.cpp */ class Example < . >;

Это отличный вариант соблюдения 2 пункта из советов.

Документация функций/методов

Функции и методы также должны документироваться строго над объявлением/описанием. Здесь я также выступаю за многострочные комментарии по тем же причинам, что и выше.

/** * Документация для функции foo */ void foo(int a, size_t b) < . >;

int sum(int a, int b)

Здесь я хочу остановится по подробнее на таком вопросе: а нужно ли документировать функцию int sum(int a, int b) ? Документирование функции/метода, по моему мнению, является самой сложной частью документации. В первую очередь, нужно руководствоваться здравым смыслом. Если сигнатура, имена функции и ее аргументов достаточно тривиальны (как в примере выше) — документирование может быть излишне. Но действительно ли все так тривиально? Действительно ли возвращаемое значение и имя функции говорит лучше любого комментария? Подумайте об этом, когда встанет вопрос документации функции/метода.

Для функции будет удобно не только задокументировать описание функции, но и ее сигнатуру — возвращаемый тип, аргументы. Если функция возвращает unordered_map , то возможно стоит объяснить содержание такого ассоциативного массива.

Опишите поведение функции/метода в случае ошибки (что возвращает, какие исключения кидает). Для этого можно использовать команду @throw.

Помните — документация в коде должна избавлять программиста от необходимости переходить к описанию кода.

/** * Это описание функции foo * * @param str это описание аргумента str * @param pattern это описание аргумента pattern * @return это описание того, что вернет функция */ int foo(std::string str, std::string& pattern) < . >;

Было бы несправедливо не упомянуть о минусе документирования методов в хедере — захламление интерфейса класса («Зачем?», пункт 4). К счастью Doxygen, как и CLion, определяет документацию и в cpp файлах. Поэтому описание методов класса можно выносить из хедеров.

Документация членов в классе/структуре, переменных в функции, значений в перечислениях

Для таких объектов будет удобен такой стиль документации:

int result; ///< Краткое описание переменной result

/// Краткое описание переменной result int result;

Или на крайний случай

/** * Длинное описание переменной var, * которое не поместилось в одну строку */ int var;

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

Более подробно о технических деталях документации рассказано тут.

Как обеспечить качественную документацию?

Самый очевидный вариант, проверять присутствие документации на ревью. Нет документации - нет MR, все просто. Но как гарантировать нам, что документация действительно получится качественной и понятной? Один из возможных вариантов - доверить ревью документации младшим и средним специалистам.

Если доверить ревью документации вашему опытному коллеге/сотруднику, большая вероятность того, что проверка документации получится некачественной. Опытный программист на то и опытный, что ему не составляет труда разобраться в новом коде. Он прошел через огонь и воду, методы в сотни строк и полную неразбериху в структуре проекта. Для него любая ваша документация - это подарок. Даже если он очень хочет провести качественное ревью, есть риски, что у него это не получится. Что поделать, горе от ума:(

Доверить ревью новичку даст два больших плюса:

Первое - это гарантия качественной документации. Если ваши комментарии понял новичок, его поймет любой другой специалист.

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

Понятно, что первое время новичок, возможно, будет стесняться делать замечания своим более опытным коллегам или вообще не понимать что от него требуют. Но если специалист перспективный (заодно и проверите), такое поведение - вопрос времени. Новичку предоставляется возможность поглядеть на код своих более опытных коллег, повзаимодействовать с ними. Это ли не перенимание опыта?

В перспективе вы получите:

1. Подробную и качественную документацию
2. Более быстрый рост и включение в проект своих новых сотрудников

Резюме

Понятно, что все, о чем я рассказал выше, "хорошо только на бумаге". Вероятней всего, на практике вы столкнетесь с трудностями: негодование ваших коллег/сотрудников о "бесполезной" работе, "бедной" документации, несогласия о стиле. Но не мне вам говорить, что такие изменения никогда не даются легко:) Грамотный подход к решению вопроса документации в перспективе окупит себя.

Ссылки, которые помогли мне к подготовке данного материала:

Документирование кода в Python. PEP 257

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

PEP 257 описывает соглашения, связанные со строками документации python, рассказывает о том, как нужно документировать python код.

Цель этого PEP - стандартизировать структуру строк документации: что они должны в себя включать, и как это написать (не касаясь вопроса синтаксиса строк документации). Этот PEP описывает соглашения, а не правила или синтаксис.

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

Что такое строки документации?

Строки документации - строковые литералы, которые являются первым оператором в модуле, функции, классе или определении метода. Такая строка документации становится специальным атрибутом __doc__ этого объекта.

Все модули должны, как правило, иметь строки документации, и все функции и классы, экспортируемые модулем также должны иметь строки документации. Публичные методы (в том числе __init__) также должны иметь строки документации. Пакет модулей может быть документирован в __init__.py.

Для согласованности, всегда используйте """triple double quotes""" для строк документации. Используйте r"""raw triple double quotes""", если вы будете использовать обратную косую черту в строке документации.

Существует две формы строк документации: однострочная и многострочная.

Однострочные строки документации

Однострочники предназначены для действительно очевидных случаев. Они должны умещаться на одной строке. Например:

 Используйте тройные кавычки, даже если документация умещается на одной строке. Потом будет проще её дополнить.

Закрывающие кавычки на той же строке. Это смотрится лучше.

Нет пустых строк перед или после документации.

Однострочная строка документации не должна быть "подписью" параметров функции / метода (которые могут быть получены с помощью интроспекции). Не делайте:

 list"""

Этот тип строк документации подходит только для C функций (таких, как встроенные модули), где интроспекция не представляется возможной. Тем не менее, возвращаемое значение не может быть определено путем интроспекции. Предпочтительный вариант для такой строки документации будет что-то вроде:

(Конечно, "Do X" следует заменить полезным описанием!)

Многострочные строки документации

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

Вставляйте пустую строку до и после всех строк документации (однострочных или многострочных), которые документируют класс - вообще говоря, методы класса разделены друг от друга одной пустой строкой, а строка документации должна быть смещена от первого метода пустой строкой; для симметрии, поставьте пустую строку между заголовком класса и строкой документации. Строки документации функций и методов, как правило, не имеют этого требования.

Строки документации скрипта (самостоятельной программы) должны быть доступны в качестве "сообщения по использованию", напечатанной, когда программа вызывается с некорректными или отсутствующими аргументами (или, возможно, с опцией "-h", для помощи). Такая строка документации должна документировать функции программы и синтаксис командной строки, переменные окружения и файлы. Сообщение по использованию может быть довольно сложным (несколько экранов) и должно быть достаточным для нового пользователя для использования программы должным образом, а также полный справочник со всеми вариантами и аргументами для искушенного пользователя.

Строки документации модуля должны, как правило, перечислять классы, исключения, функции (и любые другие объекты), которые экспортируются модулем, с краткими пояснениями (в одну строчку) каждого из них. (Эти строки, как правило, дают меньше деталей, чем первая строка документации к объекту). Строки документации пакета модулей (т.е. строка документации в __init__.py) также должны включать модули и подпакеты.

Строки документации функции или метода должны обобщить его поведение и документировать свои аргументы, возвращаемые значения, побочные эффекты, исключения, дополнительные аргументы, именованные аргументы, и ограничения на вызов функции.

Строки документации класса обобщают его поведение и перечисляют открытые методы и переменные экземпляра. Если класс предназначен для подклассов, и имеет дополнительный интерфейс для подклассов, этот интерфейс должен быть указан отдельно (в строке документации). Конструктор класса должен быть задокументирован в документации метода __init__. Отдельные методы должны иметь свои строки документации.

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

И, напоследок, пример:

 А ещё больше примеров можно посмотреть в стандартной библиотеке python (например, в папке Lib вашего интерпретатора python).

Для вставки кода на Python в комментарий заключайте его в теги

"""Модуль содержит классы плоских фигур.""" from math import pi, pow class Rectangle: """Класс Прямоугольник.""" def __init__(self, a, b): """Конструктор принимает длину и ширину.""" self.w = a self.h = b def square(self): """Метод для вычисления площади.""" return round(self.w * self.h, 2) def perimeter(self): """Метод для вычисления периметра""" return 2 * (self.w + self.h) class Circle: """Класс Круг.""" def __init__(self, radius): """Конструктор принимает радиус.""" self.r = radius def square(self): """Метод для вычисления площади круга.""" return round(pi * pow(self.r, 2), 2) def length(self): """Метод для вычисления длины окружности.""" return round(2 * pi * self.r)

>>> import planimetry >>> planimetry.Rectangle.__doc__ 'Класс Прямоугольник.' >>> print(planimetry.__doc__) Модуль содержит классы плоских фигур.

>>> help(planimetry.Circle.length) Help on function length in module geometry.planimetry: length(self) Метод для вычисления длины окружности.

>>> print(str.__doc__) str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

>>> import math >>> print(math.trunc.__doc__) Truncates the Real x to the nearest Integral toward 0. Uses the __trunc__ magic method. >>>