Лучше ли документировать функции в заголовочном файле или исходном файле?

На языках, которые различают исходный файл и файл заголовка (в основном C и C ++), лучше документировать функции в заголовочном файле:

(ворованный из CCAN )

/**
 * time_now - return the current time
 *
 * Example:
 *  printf("Now is %lu seconds since epoch\n", (long)time_now().tv_sec);
 */
struct timeval time_now(void);

или в исходном файле?

(украдено из PostgreSQL)

/*
 * Convert a UTF-8 character to a Unicode code point.
 * This is a one-character version of pg_utf2wchar_with_len.
 *
 * No error checks here, c must point to a long-enough string.
 */
pg_wchar
utf8_to_unicode(const unsigned char *c)
{
...

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

Вот некоторые аргументы, которые я могу придумать. Я склоняюсь к документированию в исходном файле, поэтому мои аргументы «Pro-header» могут быть несколько слабыми.

Pro-заголовок:

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

Pro-источник:

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

При ответе, пожалуйста, будьте осторожны с аргументами, основанными на том, что могут сделать инструменты и «современные IDE». Примеры:

• Pro-header: свертывание кода может помочь сделать заголовки с комментариями более удобными, скрывая комментарии.
• Pro-источник: Cscope «s Find this global definitionфункция принимает вас к исходному файлу (где определение является) , а не файл заголовка (где декларация является).

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

Мой вид...

• Документ о том, как использовать функцию в заголовочном файле или, точнее, близко к объявлению.

• Документируйте, как работает функция (если это не очевидно из кода) в исходном файле или, точнее, близко к определению.

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

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

Если вы собираетесь использовать такой инструмент, как Doxygen (обратите внимание, в первом примере, который действительно выглядит как комментарий Doxygen, потому что он начинается с /**), тогда это не имеет значения - Doxygen будет просматривать заголовок и исходные файлы и находить все комментарии для генерации документации.

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

Если вы посмотрите на большинство библиотек Linux, например, ваша система управления пакетами Linux часто имеет пакет, который содержит только двоичные файлы библиотеки (для «обычных» пользователей, у которых есть программы, которым нужна библиотека), и у вас есть пакет «dev», который содержит заголовки для библиотеки. Исходный код обычно не поставляется напрямую в пакете. Было бы очень обременительно, если бы вам нужно было где-нибудь получить исходный код библиотеки, чтобы получить документацию по API.

Мы решили эту проблему (около 25 лет назад), создав кучу #defines (например, public, private и т. Д., Которые были преобразованы в <nothing>), которые могли бы использоваться в исходном файле и сканироваться скриптом awk (ужасы). !) для автоматической генерации .h файлов. Это означает, что все комментарии жили в источнике и были скопированы (при необходимости) в сгенерированный файл .h. Я знаю, что это довольно старая школа, но она значительно упростила этот вид встроенной документации.

Предполагая, что это код в более крупном проекте (где разработчики будут часто перемещаться между источником и заголовками) , и если это не библиотека / промежуточное ПО, где другие могут не иметь доступа к источнику, я нашел, что это работает Лучший...

• Заголовки:
  краткие 1-2-строчные комментарии, только если они необходимы.
  Иногда полезны также комментарии над группой связанных функций.
• Источник:
  Документация по API непосредственно над функцией (простой текст или doxygen, если вы предпочитаете) .
• Сохраняйте детали реализации, относящиеся только к разработчику, изменяющему код в теле функции.

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

Конечно, вы можете выбрать соглашение и убедиться, что все разработчики следуют ему. Я только что нашел соглашение выше самого естественного соответствия и вызывает наименьшее количество проблем для поддержания.

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

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

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

Но это только я ...

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

Если заинтересованные стороны вашего исходного кода (скажем, небольшая библиотека) состоят из «пользователей» (коллег-разработчиков, которые будут использовать функциональные возможности вашей библиотеки без участия в ее реализации) и «разработчиков» (вы и другие разработчики, которые будут реализовывать библиотеку) затем поместите «информацию о пользователях» в заголовок и «примечание к реализации» в источнике.

Что касается желания не менять заголовочные файлы больше, чем это абсолютно необходимо - я полагаю, если ваша библиотека не «в сумасшедшем потоке изменений», то «интерфейс» и «функциональность» не сильно изменятся, и ни если комментарии заголовка меняются слишком часто. С другой стороны, комментарии исходного кода должны быть синхронизированы («свежие») с исходным кодом.

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