Документирование кода в Python
Д окументирование кода — неотъемлемая часть разработки на Python. Порой документации в коде может быть больше, чем самого кода. Она помогает понять, что делает функция или класс, какие аргументы принимает и что возвращает.
Когда документация и код находятся в разных местах, сопровождать их становиться довольно тяжело. Поэтому на практике документация находится непосредственно рядом с кодом.
Docstring
Документация для классов
Документация класса создается для самого класса, а также для его методов.
class Speaker: «»»Это docstring класса Speaker»»» def say_something(self): «»»Это docstring метода»»» print(«something»)
После строки документации нужно оставлять пустую строку
Документация для класса может содержать следующую информацию:
Для методов класса документация может содержать:
Ниже — пример с более подробной документацией класса:
Документация для пакетов
Документация пакета размещается в файле __init__.py в верхней части файла (начиная с 1-й строки). В ней может быть указано:
Документация для модулей
Документация модулей аналогична документации классов. Вместо класса и методов в данном случае документируется модуль со всеми его функциями. Размещается в верхней части файла (начиная с 1-й строки).
Форматы Docstring
Строки документации могут иметь различное форматирование. В примере выше мы использовали стиль NumPy. Существуют и другие форматы:
Вывод документации на экран — help() и __doc__
Строки документации доступны:
Выведем документацию с помощью функции help()
Также можно выводить документацию отдельного объекта:
>>> import my_module >>> my_module.__doc__ >>> my_module.my_function.__doc__ >>> my_module.MyClass.__doc__ >>> my_module.MyClass.my_method.__doc__
Pydoc
Для более удобной работы с документацией, в Python существует встроенная библиотека pydoc.
Pydoc автоматически генерирует документацию из Python модулей. Информацию по доступным командам модуля pydoc можно получить набрав в терминале:
Разберем подробнее, что умеет pydoc.
Вывод текста документации
pydoc — покажет текст документации указанного модуля, пакета, функции, класса и т.д. Если содержит «\», Python будет искать документацию по указанному пути.
Для примера, посмотрим документацию встроенного модуля math:
В консоль выведется название модуля, его описание и описание всех функций в модуле.
Поиск по документации
Допустим, нам нужно распаковать gzip файл. Поищем слово » gzip «:
По описанию, данный модуль решит нашу задачу.
HTTP сервер с документацией
Для удобства просмотра документации, pydoc позволяет одной командой создать HTTP-сервер:
Теперь можно перейти в браузер и зайти на http://localhost:331/
Для остановки сервера введите » q » и нажмите » Enter «:
server> q Server stopped
Запись документации в файл
Автодокументирование кода
Pyment работает следующим образом:
Этот инструмент особенно полезен когда код плохо задокументирован, или когда документация вовсе отсутствует. Также pyment будет полезен в команде разработчиков для форматирования документации в едином стиле.
pip install pyment
Для большинства IDE также существуют плагины, помогающие документировать код:
В PyCharm существует встроенный функционал добавления документации к коду. Для этого нужно:
Пять стратегий документирования кода
В этом разделе мы рассмотрим подходы к фактическому документированию кода. Существует несколько подходов, которыми пользуются писатели и инженеры, мы познакомимся с пятью из них с примерами и комментариями.
После прочтения вступления к модулю “Документирование кода” одна из читательниц поделилась своим подходом. Вот, что она написала:
Кажется, такое разделение и расположение комментариев кода имеет место быть. Можно разделять пояснения на две основные категории:
После разделения, пояснения Как? встраиваются в код в виде комментариев (примерно на каждые 5-10 строк). Пояснения Почему? встраиваются во внешних разделах до или после кода. Разумеется, в пояснениях Как? можно получить подробную информацию о Почему? причинах, и наоборот, поэтому разделение этих двух вопросов на практике может быть не таким простым. Но такая общая закономерность, скорее всего, верна.
Кроме того, такой подход интересен тем, что он побуждает подумать над вопросом Почему?. Техническим писателям, документирующим код (который пишут другие), не всегда получается учитывать Почему?.Иногда бывает трудно понять, какие вопросы Почему? существуют. Зачем использовать этот класс вместо другого? Почему так, а не так? Часто существует много разных способов достижения цели, так почему же идти по этому пути, а не каким-то другим?
В общении с разработчиками о примерах кода, стоит задавать это вопрос: Почему?
Подход 2: сопоставление комментариев в третьей колонке
Лучшие практики для документации в целом (не только для документирования кода) включают размещение полезных инструкций рядом с областью, вызывающей затруднения, что в контексте документирования кода может означать добавление встроенных комментариев, пронизывающих весь код. Но предположим, что нужен большой комментарий о том, что происходит в коде (поскольку уровень сложности не может быть передан в коротком комментарии). Как сопоставить длинную концептуальную / пояснительную информацию с кодом?
Если ваш комментарий больше кода, есть риск сделать код нечитаемым. Если разместить комментарий в разделах, которые идут задолго до или после кода, есть риск создать пропасть между объяснением и кодом, так что читатели не будут знать, к каким частям кода относится объяснение.
Документация Twilio, с третьей колонкой для кода
В этом примере концептуальное содержание и шаги появляются в средней колонке, код справа, на темном фоне для создания визуального контраста.
Некоторые экраны Twilio фактически “размывают” нерелевантный код, позволяя сосредоточить свое внимание на линиях, сформулированных в концептуальной области, например:
Размытие нерелевантного кода
Одной из проблем такого подхода является пространство экрана. Чтобы добавить третью колонку, нужно занять весь экран без полей. (Странно, что в Twilio нет возможности свернуть левую панель навигации, освободив тем самым больше места для кода.)
Таким образом, код виден только частично. Код можно растянуть по горизонтали с возможностью прокрутки вправо, но, несомненно, дизайнерам тяжело дался пользовательский интерфейс, который включает в себя горизонтальную и вертикальную прокрутку.
Вдобавок, реализация размытия фокуса области экрана с кодом, на описании которого находится пользователь, должна быть технически сложной и громоздкой.
Другая проблема заключается в том, что код и пояснения к нему редко можно выровнять линейно. Предположим, есть метод в коде, который занимает всего одну строку, но описание этого метода занимает три длинных параграфа концептуального объяснения. К тому времени, когда пользователь достигает нижней части концептуального объяснения, код уже не виден. Пользователю приходится сделать много лишних манипуляций, чтобы найти соответствующий код. Дизайн пользовательского интерфейса для размещения всех этих движущихся частей не только кажется сложным, но и увеличивает нагрузку на пользователя.
Еще одна проблема, связанная с таким дизайном, заключается в том, что код часто относится к нескольким файлам. Отображение в колонке не указывает, отображается ли весь код в одном и том же файле Java или мы видим код из нескольких файлов Java. Представление вкладок в столбце кода требует еще более сложного формата документации. Сложно представить, что все это возможно сделать с помощью синтаксиса Markdown.
Подход 3: подход Лего
Другой подход заключается в создании кода с нуля, уровня за уровнем, который можно назвать “подходом Лего”. В качестве примера подхода Лего можно посмотреть на пример в eBay Shopping API Поиск по продавцу: Просмотр информации о продавце.
Подход Лего показан в API eBay Shopping
У них в руководстве всего 5 шагов:
Проблема с подходом Лего заключается в том, что технический писатель вряд ли воссоздаст логику построения, которой следовал разработчик. Скорее всего, разработчики просто отправят готовый кусок кода в документ, и тогда придется получать пояснения от разработчика о коде, как описано в разделе Почему так трудно документировать код?, где описаны основные проблемы.
Несмотря на проблемы с подходом Лего, если нужно научить кого-то, как понимать код, нужно начать с простого и идти шаг за шагом от простого к сложному. Следующая техника объясняет такой подход от простого к сложному при помощи метафоры наутилуса.
Подход 4: подход Наутилус
Подход Наутилус аналогичен подходу Лего, но вместо того, чтобы описывать куски работы, которые выполняются один за другим в порядке сборки, здесь описываются основные простые шаблоны, которые должны знать пользователи. Начинается с самого простого кода, а затем проект увеличиваться и увеличиваться по мере необходимости, как растущая спиральная структура оболочки наутилуса.
Пол Густафсон, управляющий компанией, занимающейся техническим обслуживанием письма, в Bay Area, которая называется Экспертная поддержка, представляет подход с метафорой Наутилуса, описанный здесь. Пол говорит, что наутилус является хорошей метафорой для технической коммуникации, потому что наутилус представляет спиральную схему (последовательность Фибоначчи), которая начинает с малого и постепенно растет по мере необходимости:
Следуя подходу Наутилус, мы начинаем с простых базовых шаблонов, а затем постепенно наращиваем объем кода вокруг него по мере необходимости. Мы не начинаем с описания сложной законченной работы с самого начала. Законченная работа, вероятно, включает в себя все виды абстракций кода и перестановки для чистого, готового продукта.
Проблема в том, что мы часто хотим объяснить, как работает готовый код, проводя пользователя через все от начала до конца. У нас может быть 500 строк кода, которые мы хотим сформулировать, но подход Nautilus заставил бы нас объяснить только несколько небольших фрагментов этого кода (по крайней мере, для начала). Следовательно, существует проблема типа A-против-Z: мы описываем A (самый простой шаблон ядра), но конечным продуктом является Z. Как именно мы добираемся от A до Z? Как мы придем от простых шаблонов, которые могут занимать 20 строк кода, до чудовищно сложного, законченного кода, который занимает 500 строк?
Для технического писателя, смотрящего на окончательный код, нет ясного понимания того, как разработчик попал туда. Мы часто не можем отделить подобную логику, с которой начинал разработчик, что привело его к этой более сложной цели. Все, что мы видим, это этот сложный конец. Как декомпилировать код, чтобы восстановить логику, с которой разработчик начал? Как понять, что это были за начальные паттерны, которые положили начало всему процессу? Если вы не разрабатывали код и не являетесь разработчиком, то будет практически невозможно восстановить шаблон Наутилуса, стоящий за кодом.
Как задокументировать процесс создания картины?
Чтобы задокументировать процесс создания такой картины, что лучше: начать с верха и идти к низу? Нет, это было бы смешно. Скорее всего, лучше начинать с создания овала головы. Потом, несколько общих набросков для глаз и так далее. Может быть, набросать линии перспективы и другую основную структуру. Никто сразу не приступает к цветам, освещению и теням, верно? То же самое с кодом. Начинаем с основы, а затем прокладываем путь к большему количеству завершающих деталей.
Чтобы проиллюстрировать этот момент более четко, приведем пример кода. Автор курса не инженер, но ему удобно работать с Jekyll и темами, он создал шаблон, который будет принимать экспорт контента из инструмента для создания тикетов (например, JIRA) и отображать его в виде отчета документации на веб-странице.
Финальный шаблон выглядит так:
Этот код выглядит как бред, правда. Здесь есть несколько инклюдов, в которых абстрагирована логика, потому что они будут повторяться ее из отчета в отчет. Здесь убраны скрипты и стили, так как они загромождают код, поэтому они хранятся во включаемых файлах.
Представьте, что вы пытаетесь задокументировать этот код. Если бы вы начали сверху и дошли до конца, это было бы настоящим беспорядком. Пользователю также будет трудно читать длинное объяснение. Такой запутанный клубок. И он не распутается, если поспешно собрать все, не задумываясь о чистом, элегантном решении. Нужно было быстро выпустить отчет, поэтому шаблон был взломан как можно быстрее. Разработчики, создающие приложения, часто внедряют подобные хаки и другие костыли, используя скотч и WD-40, как говорит Джоэл Спольски, чтобы получить рабочее решение, поставленное в срок.
Даже этот кусок сбивает с толку, поскольку есть странные вещи с переменными, вставленными в скобки в ссылках на файл YAML.
Чтобы по-настоящему объединить код с основной логикой, разработчики должны начать с этого:
Чтобы собрать эту информацию, нужно взять интервью у разработчика. И при общении с разработчиком, нужно понимать его язык и объяснения. В качестве альтернативы можно попросить разработчика описать логику собственного кода с помощью руководства с правильными вопросами. Например, можно спросить:
Подход 5: Интерактивный браузер
Изучение основных шаблонов смещает документацию в область руководства. С этим типом обучения связан интерактивный браузер, в котором действие сочетается с обучением. Интерфейсы, выполняемые браузером, имеют своей целью помочь пользователям лучше понять результаты входных и выходных данных, чтобы пользователи могли сами убедиться в том, как работает код, используя более практичный для себя подход.
Кнопка Try it out в интерфейсе Swagger
Swagger предлагает оригинальное сочетание документации с активным взаимодействием, которые помогают пользователям изучать API (читая и выполняя). Но выполнение запросов с помощью конечных точек API REST обычно довольно простое. Более интенсивные руководства по коду будет сложнее сделать интерактивными в браузере. Тем не менее, некоторые «Notebooks» (как их часто называют) позволяют запускать код, в частности Jupyter Notebooks. Описание Jupyter:
У Google есть несколько вариантов блокнота для совместной работы с документацией TensorFlow, в которой есть операции, которые можно выполнять на веб-страницах. На следующем скриншоте можно увидеть опцию Run code now :
Интерактивный пример кода от TensorFlow
Клик на Run code now открывает интерактивную записную книжку Google, которая фактически запускает код в браузере:
Интерактивный блокнот Google позволяет запускать код в браузере
Хотя интерактивные записные книжки выглядят круто, они кажутся огромной работой для чего-то, что может быть легко достигнуто с помощью образца приложения. Вместо того, чтобы выяснить, как вы можете скомпилировать код Python или другой язык в браузере, почему бы просто не предоставить пример приложения, которое пользователи могут загрузить, а затем выполнить локально, используя свои собственные инструменты компиляции и настройки?
Заключение
В этом разделе мы рассмотрели 5 подходов документирования кода:
Лучше использовать подход, который помогает пользователям получить нужные знания для создания собственного кода.
👨💻 Практическое занятие: сравниваем документацию кода с одним из подходов
Ищем раздел с руководством по коду на одном из сайтов документации API, которые изучали. Или посмотрите на один из сайтов документации API в этом посте от Nordic APIs: 5 Примерjd отличной документации API (и почему мы так думаем). В этом посте перечислены пять примеров документации API: Stripe, Twilio, Dropbox, GitHub и Twitter.
И попробуем выяснить, какому подходу лучше всего соответствует документация кода.
Как сделать документацию к коду?
Простой 3 комментария
Есть две крайности, которых лучше избегать:
1. красивая и исчерпывающая документация требует колоссальных ресурсов на поддержку
2. сложно воспринимаемый код, без малейших подсказок с чего все начинается и чем заканчивается
Кстати, проектная работа, это не только документация к коду, это еще и свод правил, которые позволят архитектуре не расползтись кто в лес кто по дрова, а также сохранят стилистику написания кода для единообразия и легкой поддерживаемости кода.
Думаю, вышеописанные пукнты не вяжутся с JS, хоть и прекрасно работают в других средах (php, java etc).
На JS вообще очень сложно писать «правильно» и «хорошо»))
Согласен, JSDOC, юнит тесты и автоматическая документация прекрасно работают в JS, но это, имхо, вообще не тот язык, который следует использовать в таких приложениях.
На счет 2007-го, а разве в JS уже появилась статическая типизация, интерфейсы, приватные свойства?))
Да и в сто раз проще написать hhvm совместимый код на PHP+фрейме ежели использовать его. Выйдет и быстрее, и проще, и лучше.
Как писать техническую документацию для программ на C#
Рано или поздно в жизни каждого разработчика наступает момент, когда он не понимает, как работает его код. Выясняем, что с этим делать.
Программисты часто сталкиваются с тем, что не могут прочитать код. Такое случается постоянно: когда только приходят в новый проект, когда проверяют код коллеги или — так бывает чаще всего — когда смотрят результат своей же работы. Чтобы этого избежать, нужно писать и читать документацию.
Разработчики имеют дело с двумя основными видами документации:
К сожалению, не все разработчики (практически никто) любят читать документацию. Любителей писать её и того меньше. Однако делать это очень важно, потому что сложно поддерживать проект без документации.
Пишет о разработке сайтов, в свободное время создает игры. Мечтает открыть свою студию и выпускать ламповые RPG.
Правила хорошего тона в составлении документации
Составляя документацию, стоит следовать определенным правилам — они помогают сделать ее более понятной.
1. Документация нужна не всегда
Если программа одноразовая, не стоит тратить время на написание пояснений. Например, если нужен небольшой скрипт, который будет написан за пять минут и использован 1-2 раза.
2. Документация нужна не везде
Также не нужно писать пояснения ко всему. Если код написан хорошо, то по названиям уже будет понятно, что это такое и зачем оно используется. Например, легко догадаться, что метод int Sum (int a, int b) возвращает результат сложения двух чисел.
Исключение можно сделать, если речь идет об API или фреймворке, которыми пользуются многие разработчики: они не всегда видят исходный код, но могут использовать классы и методы. Поэтому им важно иметь список доступных методов. В этом случае задокументировать всё нужно просто для галочки.
3. Документация должна быть точной
Очень важно уметь ясно выражать свои мысли. Нужно предельно точно описывать, что делает тот или иной фрагмент кода. Для этого стоит давать как можно более короткие определения. Например:
В этом фрагменте кода объем документации к классу и его свойству не превышает одного предложения. Этого достаточно, чтобы было понятно, что это такое и для чего его нужно использовать.
4. Документация должна быть сухой
Хотя канцеляризмов нужно избегать, писать надо максимально сухо и по делу. Никаких стихов, метафор, аналогий или шуток — всё это может быть забавным, но не добавляет ясности.
5. В документации не должно быть старого кода
Этот правило больше касается обычных комментариев, чем самой документации. Однако оно очень важное, поэтому приведено здесь.
Никогда не храните в коде старые методы и операторы, даже если они задокументированы. Если что-то не используется в текущий момент — это мусор, от которого нужно избавиться.
Если есть сомнения пригодится ли еще этот код, его лучше сохранить в системе контроля версий — именно для этого ее и придумали.
Дальше речь пойдет о том, как писать техническую документацию для программ на C#. Вся работа будет вестись в Visual Studio.
Где писать документацию в C#
Вариантов много. Например, можно сделать это в Word или Google Docs, тогда разработчики смогут скачивать файл из интернета. Некоторые хранят инструкции в печатном виде, но это плохой вариант, потому что документация быстро устаревает.
Лучший способ — писать всё прямо в коде программы. Тогда у каждого разработчика будет доступ к документации в любое время. Самый примитивный вариант — использовать комментарии.
В C# есть два вида комментариев. Однострочные:
Документирование кодовой базы. Зачем и как?
Введение
Недавно, на одном из митингов моей команды, была поднята проблема отсутствия документации внутри кода. Было решено назначить ответственного за ведение документации. Нужно было найти подходящие инструменты документирования, определить стиль и регламент, представить решение команде. Я решил, что возьму эту задачу на себя, так как для меня это особенно важный вопрос. Мне, как новому сотруднику, было довольно тяжело разобраться в уже существующем коде без документации, и упустить возможность повлиять на ее появление я просто не мог. В итоге, в процессе определения стандарта для нашей команды и появилась эта статья. Я подумал о том, здесь присутствуют довольно интересные мысли, поэтому решил поделиться ими здесь.
Дисклеймер
Так как я С++ разработчик, то и документирование кода я рассматриваю как документирование кода С++. Когда я говорю код, функция, метод или класс, я подразумеваю код, функцию, метод или класс на С++.
Зачем?
Здесь я приведу пару пунктов формата вопрос-ответ. Это те вопросы, которые я задавал себе сам и слышал от своих коллег, когда вставал вопрос документирования кода.
«Все и так знают наш код»
Это утверждение справедливо для разработчиков с большим опытом работы в компании, но никак не для тех, кто только включается в проект. Чем больше документации встретит новичок в коде, тем быстрее он сможет включиться в работу. 10 минут чтения документации лучше, чем 2 часа отладки кода.
«Этот код прост и не нуждается в документации»
Если такая мысль пришла вам в голову, обдумайте ее еще раз. Если подумать еще не помогло, посоветуйтесь со своими коллегами. Если ваш код не вызвал вопросов при одном только взгляде на него, то, возможно, комментирование кода действительно излишне (но это не точно). Этот пункт будет подробнее обсуждаться далее.
«Этим кодом больше никто пользоваться не будет»
Это неправда. Не использоваться он будет до поры до времени. В моей практике были моменты, когда я реализовывал то, что уже есть в нашей кодовой базе. Отсутствие документации и, соответственно, привычки искать существующие решения в ней, привели меня к дубликации кода.
Общие советы документирования
Приведите пример использования вашего кода
Оставьте названия функций/методов/классов, ткните в место, где используется ваш код. Если вы использовали какое-то популярное решение (паттерн), оставьте ссылку на материал по этой теме. Это поможет быстрее сориентироваться в коде. Понятно, что поиск в IDE даст вам ту же информацию, но иногда он бывает долгий, плюс таким образом вы сможете особенно выделить то место, где использование вашего кода продемонстрировано максимально явно.
Если решение нетривиально, расскажите о причинах такого решения
Почему использовано именно такое решение? Порой приходится много времени заниматься отладкой и изучением кода, чтобы понять, почему коллега выбрал именно такой подход. Краткий ответ на вопросы зачем и почему сэкономит много времени. Данный пункт переплетается с первым.
Постарайтесь найти середину между отсутствием документации и документированием каждой строки
Не нужно писать целую поэму для метода, из названия которого понятно, что он делает (я надеюсь, что название соответствует тому, что он делает). Также не стоит думать, что, например, простой класс не нуждается в подробной документации. Здесь важно найти золотую середину.
Не пересказывайте код
Не превращайте ваши комментарии в это
Пример того, как делать не надо
Не забывайте о поддержке документации IDE
Сейчас почти все IDE способны выводить описание класса/метода/функции при взаимодействии с ним (наведение мыши, комбинация клавиш), если описание оформлено в нужном формате. Пишите документацию так, чтобы (1) IDE смогла ее «подхватить», (2) можно было обойтись чтением документации и избежать необходимости открывать код с целью его изучения.
Дайте описание поведения вашей функции/метода в случае ошибки
Что вернет ваш код? Возможны ли исключения и какие? Если функция бросает слишком много исключений, возможно не стоит перечислять их все.
Помните о том, что ваши комментарии в будущем будут читать другие люди, в том числе и вы
Не пишите документацию ради документации, пишите ее ради облегчения работы своей команды. Задайте себе вопрос: пойму ли я, что делает этот код, через месяц, посмотреть на комментарии? Для более честного ответа, попросите ответить на этот вопрос своих коллег.
Не забывайте об актуальности документации
Неактуальная информация уже неактуальна хуже ее отсутствия.
Вопросы о грамотности, удобстве, понятности документации и прочие популярные я опускаю с надеждой на то, что такие вещи для читателя само собой разумеющееся.
Документирование можно вести в стандарте JavaDoc. Это удобный формат, который знаком многим IDE и поддерживается Doxygenом. Плюсом для нас было то, что он уже частично используется в нашем проекте, и IDE, в которых мы работаем (CLion, QtCreator, VisualStudio) прямо поддерживают генерацию комментариев в этом стандарте и их отображение.
Далее будут описаны инструменты документации и некоторые правила, которые мы приняли в своей команде.
Многострочные и однострочные комментарии
Doxygen поддерживает много видов комментариев. Для нашей команды я выделил такие:
Хочу обратить внимание, что
Также существует такой вид комментария:
Такой вариант удобен, когда нужно задокументировать одну строку внутри функции, или дать описание переменной или члену класса/метода. Обратите внимание, что между слэшем и стрелкой нет пробела.
Команды
В JavaDoc есть так называемые команды. Команды служат для детализации, выделения документации. Команд в JavaDoc довольно много, плюс можно вводить свои. Те команды, которые используем мы, я опишу далее. К сожалению, многие команды (почти все) в C++ не поддерживаются так, как хотелось бы (так, как это сделано в Java). Но тем не менее это отличный способ структурировать вашу документацию, обеспечить удобство при чтении и поддержку Doxygen. Я настоятельно рекомендую пользоваться командами.
Классы, структуры, перечисления, области видимости
Документация должна находиться строго до объявления/описания кода. Это позволит нашим IDE, и в дальнейшем Doxygenу, подхватить комментарии.
Мы документируем такой код многострочным комментарием, даже если описание влезает в одну строку.
Это позволяет комментариям не выбиваться из общего стиля документирования. Комментарии в одну строку блочного кода должны быть редкостью!
Для указания краткого описания может быть использована команда @brief. Указанный после команды текст, вплоть до конца параграфа, будет относиться к краткому описанию, и для отделения от основного используется пустая строка.
Также можно (и даже нужно) добавлять команду @example. Такой вариант позволит быстрее найти пример использования кода.
Это отличный вариант соблюдения 2 пункта из советов.
Документация функций/методов
Функции и методы также должны документироваться строго над объявлением/описанием. Здесь я также выступаю за многострочные комментарии по тем же причинам, что и выше.
int sum(int a, int b)
Опишите поведение функции/метода в случае ошибки (что возвращает, какие исключения кидает). Для этого можно использовать команду @throw.
Документация членов в классе/структуре, переменных в функции, значений в перечислениях
Для таких объектов будет удобен такой стиль документации:
Или на крайний случай
Документируйте переменные однострочными комментариями, старайтесь уместить комментарий в одну строку. Там, где это невозможно, используйте многострочные комментарии.
Более подробно о технических деталях документации рассказано тут.
Как обеспечить качественную документацию?
Доверить ревью новичку даст два больших плюса:
В перспективе вы получите:
Подробную и качественную документацию
Более быстрый рост и включение в проект своих новых сотрудников
Резюме
Понятно, что все, о чем я рассказал выше, «хорошо только на бумаге». Вероятней всего, на практике вы столкнетесь с трудностями: негодование ваших коллег/сотрудников о «бесполезной» работе, «бедной» документации, несогласия о стиле. Но не мне вам говорить, что такие изменения никогда не даются легко:) Грамотный подход к решению вопроса документации в перспективе окупит себя.
Ссылки, которые помогли мне к подготовке данного материала: