В заголовочном файле, содержащем форвардные объявления или в файле .cpp, содержащем реализации, например:
//header.h
/* About foo() */
void foo();
/* About bar() */
int bar();
/* About A */
class A
{
public:
/* About A constructor */
A();
....
}
или
//implementation.cpp
/* About foo() */
void foo()
{
...
...
}
/* About bar */
int bar()
{
...
}
/* About A constructor */
A::A()
{
...
}
Для использования информации лучше вставить в заголовок. То, что люди будут смотреть первым.
Документация действительно успешна, если никто не должен проверять ваш .cpp файл, чтобы выяснить, как использовать этот компонент.
Насколько я знаю, каждый раз, когда вы что-то меняете в файле .h, он заставляет все файлы, включенные в этот заголовочный файл, перекомпилироваться. По этой причине я поместил большинство своих комментариев в файлы .cpp.
Для С++ я помещаю "комментарии к документации" как в cpp, так и в h.
Cpp содержит код и содержит комментарии к документации по каждому основному кодовому элементу (классам, методам и т.д.), которые описывают их, как правило, с использованием формата комментариев для doxygen или Documentation XML (хотя я не склонен генерировать внешние документы, я считают целесообразным придерживаться стандартизованного формата, который может быть извлечен для внешних инструментов, если/когда я решу, что хочу этого). Это полная документация, в которой объясняется, каким образом вызывающий должен использовать метод, а также любые детали дизайна, которые должны быть поняты любым, кто хочет изменить код, поэтому они понимают намерение, "договор" и любые важные вещи для понимания о работе кода. (Я написал addin для Visual Studio, AtomineerUtils, что делает создание и обновление этих комментариев быстрым и легким, так что это действительно не так много стараться документировать такие вещи последовательно и всесторонне)
Мой заголовок рассматривается как сводка (как для компилятора, так и для меня самого) - он использует однострочный//комментарий, который кратко описывает каждый метод. Это дает больше информации, чем имена методов/параметров (надеюсь, относительно самодокументирующихся), но намного меньше, чем подробная документация в cpp. Подумайте об этом как о сводке или напоминании, которое поможет вам взглянуть на фактическую реализацию, чтобы получить достаточно подробностей, чтобы использовать этот метод большую часть времени.
Если вы используете какой-то генератор автоматической документации, комментарии должны идти везде, где он говорит вам, что они должны идти.
В противном случае я помещаю общие комментарии "эта функция делает X" рядом с определением функции, а не объявлением функции (если, конечно, функция не объявлена в ее определении).
Поскольку объявления функций могут быть немного громоздкими, размещение документации в заголовочном файле обычно упрощает просмотр всех комментариев, относящихся к данному классу сразу, что позволяет понять понимание другими разработчиками этого класса с первого взгляда.
Вы должны поместить свои комментарии в объявление файлов, то есть в файле заголовка или интерфейса, который заканчивается расширением .h.
Возможно, для распространения вы отправляете файлы заголовков напрямую и .cpp в двоичной форме, то есть не читаемы, поэтому, если вы ожидаете, что кто-то прочитает ваши комментарии, они должны быть внутри файла заголовка.
Есть также документация по внедрению, которая имеет свое естественное место в файле .cpp.
В любом случае лучше использовать инструмент документации и изучить два или три тега usefult Javadoc, которые так часто используются. Вы должны изменить комментарий открытия к///или/**
//header.h
/** @brief About power()
@see lpower
@param x The base to power
@param y The exponent, number of times to multiply base by itself
@return x^y
*/
int power(int x, int y);
Если вы используете Doxygen, он также будет генерировать документацию, но если документация появляется как в заголовке, так и в реализации, заголовок имеет прецедент, поэтому избегайте дублирования и документируйте заголовок.
Также заголовок определяет пользовательский интерфейс, который интересует пользователя класса. Кроме того, если вы развернули код как библиотечный или объектный код, заголовок является единственным источником, к которому пользователь будет иметь доступ.