Где записывать функции в C?

Question

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

Как я могу документировать функции в комментариях?

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

Answer 1

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

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

Answer 2

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

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

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

Answer 3

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

Answer 4

Вы могли бы просто использовать Doxygen .. Кроме того, вы можете посмотреть на this answer.

Answer 5

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

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

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

Answer 6

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

Answer 7

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

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

Answer 8

Мне нравится следовать Google C++ Style Guide.

Который говорит:

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

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

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

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

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

Answer 9

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

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

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

Answer 10

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

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

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

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

Answer 11

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