C ++: где писать код документации: в .cpp или in. hpp файлы? [закрыто]
Где обычно пишется документация классов и методов в коде?
Вы пишете такие doc-блоки над соответствующим классом / методом в файле заголовка (.hpp) или в исходном файле (.cpp)?
Существует ли широко распространенное соглашение для таких вещей? проекты делают это в одну сторону, а не в другую?
Или документация должна быть написана с двух сторон (то есть в файлах .hpp и .cpp), возможно, с одним кратким описанием с одной стороны и более длинным с другой сторона?
Самое главное, Существуют ли какие-либо практические соображения, которые делают его более удобным, чтобы писать это так, а не иначе? (Например, использование автоматических анализаторов и генераторов документации, таких как Doxygen ...)
4 ответа
Если вы создаете библиотеку, вы обычно распространяете скомпилированную библиотеку и файлы заголовков. Это делает наиболее полезным размещение документации в заголовочных файлах.
Самое главное, есть ли практические соображения, которые делают его удобнее писать в одну сторону а не наоборот?
Предположим, вы хотите добавить пояснение к одному из ваших комментариев, не меняя код. Проблема в том, что ваша система сборки увидит только то, что вы изменили файл, и без необходимости предполагает, что его нужно перекомпилировать.
Если комментарии находятся в файле .cpp, он просто перекомпилирует этот файл. Если комментарии находятся в файле .hpp, будет перекомпилирован каждый файл .cpp, зависящий от этого заголовка. Это хорошая причина, чтобы ваши комментарии были в файлах .cpp.
(Например, использование автоматических парсеров документации и генераторы, такие как Doxygen...)
Doxygen позволяет писать комментарии любым способом.
Лично мне нравится документация в заголовочных файлах. Однако есть и те, кто считает, что документацию следует помещать в исходные файлы. Причина в том, что когда что-то меняется, документация тут же напоминает вам об обновлении. В чем-то согласен, так как лично я забыл обновить комментарии Doxygen в шапке, когда что-то менял в исходных файлах.
Я по-прежнему предпочитаю, чтобы комментарии Doxygen находились в заголовочном файле по эстетическим соображениям, а старые привычки трудно изменить. Я пробовал и то, и другое, и Doxygen предлагает гибкость документирования либо в исходных файлах, либо в заголовочных файлах.
Опять же оба. Что касается общедоступной документации, то хорошо иметь ее в формате .h, например, в формате, извлекаемом с помощью Doxygen, как прокомментировал другой. Мне очень нравится Perl способ документирования вещей. Файл .pl (или .pm) включает в себя документацию, которую можно извлечь с помощью инструмента, аналогичного тому, что Doxygen делает для кода C++. Кроме того, Doxygen позволяет создавать несколько разных страниц, которые позволяют включать руководства пользователя и т. д., а не только документировать исходный код или API. Мне вообще нравится идея автономного файла .h/.hpp в философии грамотного программирования.