Где документировать функции в C или C++?

У меня есть программа на C с несколькими файлами, поэтому у меня есть, например, stuff.c который реализует несколько функций, и stuff.h с прототипами функций.

Как я должен идти о документировании функций в комментариях?

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

Этот вопрос и его ответы также относятся к коду C++ - см. Также Куда следует размещать комментарии к документации?

Ответ 1

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

Ответ 2

Вам следует использовать такой инструмент, как doxygen, поэтому документация генерируется специально созданными комментариями в исходном коде.

Ответ 3

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

Что говорит:

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

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

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

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

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

Ответ 4

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

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

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

Ответ 5

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

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

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

Ответ 6

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

Ответ 7

Вы можете просто использовать doxygen. Кроме того, вы можете посмотреть на этот ответ.

Ответ 8

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

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

Ответ 9

Это просто, когда вы думаете об этом.

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

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

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

Ответ 10

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

Ответ 11

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

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

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