Where to document functions in C or C++? [closed]

Я написал простой сценарий, который принимает в качестве входных данных файл заголовка шаблона без объявлений функций и файл исходного кода с функциями с комментариями. Сценарий извлекает комментарий перед определением функции из файла исходного кода и записывает его и соответствующее объявление функции в выходной файл заголовка. Это гарантирует, что 1) есть только одно место, где нужно написать комментарий к функции; и 2) документация в файле заголовка и файле исходного кода всегда синхронизируются. Комментарий к реализации функции помещается в тело функции и не извлекается.

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

Часто это зависит от того, что установлено в качестве стандарта кодирования. Многие люди предпочитают помещать документацию в файл .h, а реализацию оставлять в файле .c. Многие IDE с автозавершением кода также легче поймут это, а не документацию в файле .c.

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

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

Я ходил туда-сюда по этому вопросу и в конце концов остановился на документации в заголовочных файлах. Для подавляющего большинства API в C/C++ у вас есть доступ к исходному заголовочному файлу и, следовательно, ко всем комментариям, которые находятся в [1]. Размещение комментариев здесь увеличивает вероятность того, что разработчики увидят их.

Тем не менее, я избегаю дублирования комментариев между заголовком и исходным файлом (это кажется пустой тратой времени). Это действительно раздражает при использовании Vim, но большинство IDE подхватывают комментарии к заголовочному файлу и помещают их в такие вещи, как intellisense или справку по параметрам.

[1] Исключениями из этого правила являются сгенерированные файлы заголовков из определенных COM-библиотек.

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

Вы можете просто использовать doxygen.. Также вы можете посмотреть этот ответ .

Это действительно просто, если подумать.

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

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

Никогда не дублируйте документацию в нескольких местах. Его будет невозможно поддерживать, и он выйдет из синхронизации почти сразу же, как только кто-то его изменит.

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

Используйте что-то вроде doxygen, чтобы создать «красивую» версию документации.

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

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

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

Мне нравится следовать Руководству по стилю Google C++ .

В котором говорится:

Объявления функций

• Каждое объявление функции должно иметь комментарии непосредственно перед это то, что описывает, что функция делает и как его использовать. Эти комментарии должны быть описательными («Открывает файл»), а не императив («Открыть файл»); в комментарий описывает функцию, это не говорит функции, что делать делать. В общем, эти комментарии не описать, как работает функция его задача. Вместо этого должно быть оставил комментарии в функции определение.

Определения функций

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

  Обратите внимание, что вы не должны просто повторять комментарии, данные с функцией декларации в файле .h или где бы. Это нормально, чтобы повторить кратко, что делает функция, но в центре внимания должны быть комментарии о том, как это делается.