С++: где писать документацию кода: в .cpp или в .hpp файлах?

Где обычно написано внутрикодовая документация классов и методов?

Вы пишете такие doc-блоки над соответствующим классом/методом в файле заголовка (.hpp) или в исходном файле (.cpp)?

Существует ли широко распространенная конвенция для таких вещей? Большинство проектов на С++ делают это в одном направлении, а не в другом?

Или должна ли быть написана документация с двух сторон (т.е. в файлах .hpp и .cpp), может быть, с одним коротким описанием одна сторона и более длинная с другой стороны?

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

Ответы

Ответ 1

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

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

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

Ответ 2

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

Ответ 3

Опять же, оба. Что касается публичной документации, приятно быть в формате .h с форматом, который можно извлечь с помощью Doxygen, например, как прокомментировал другой. Мне очень нравится Perl-процесс документирования вещей. Файл .pl(или .pm) содержит документацию сама по себе, которую можно извлечь с помощью инструмента, аналогичного тому, что Doxygen делает для кода на С++. Кроме того, Doxygen позволяет создавать несколько разных страниц, что позволяет включать в себя руководства пользователя и т.д., А не только документацию об исходном коде или API. Мне вообще нравится идея автономного файла .h/.hpp в философии грамотного программирования.

Ответ 4

Самое главное, есть ли какие-либо практические соображения, которые делают это более удобно писать это в одну сторону а не наоборот?

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

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

(например, использование парсеров автоматической документации и генераторы, такие как Doxygen...)

Doxygen позволяет вам писать свои комментарии в любом случае.

Ответ 5

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

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