Где я должен писать комментарии к документации?

В заголовочном файле, содержащем форвардные объявления или в файле .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()
{
    ...
}

Ответы

Ответ 1

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

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

Ответ 2

Насколько я знаю, каждый раз, когда вы что-то меняете в файле .h, он заставляет все файлы, включенные в этот заголовочный файл, перекомпилироваться. По этой причине я поместил большинство своих комментариев в файлы .cpp.

Ответ 3

Для С++ я помещаю "комментарии к документации" как в cpp, так и в h.

Cpp содержит код и содержит комментарии к документации по каждому основному кодовому элементу (классам, методам и т.д.), которые описывают их, как правило, с использованием формата комментариев для doxygen или Documentation XML (хотя я не склонен генерировать внешние документы, я считают целесообразным придерживаться стандартизованного формата, который может быть извлечен для внешних инструментов, если/когда я решу, что хочу этого). Это полная документация, в которой объясняется, каким образом вызывающий должен использовать метод, а также любые детали дизайна, которые должны быть поняты любым, кто хочет изменить код, поэтому они понимают намерение, "договор" и любые важные вещи для понимания о работе кода. (Я написал addin для Visual Studio, AtomineerUtils, что делает создание и обновление этих комментариев быстрым и легким, так что это действительно не так много стараться документировать такие вещи последовательно и всесторонне)

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

Ответ 4

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

В противном случае я помещаю общие комментарии "эта функция делает X" рядом с определением функции, а не объявлением функции (если, конечно, функция не объявлена в ее определении).

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

Ответ 5

Вы должны поместить свои комментарии в объявление файлов, то есть в файле заголовка или интерфейса, который заканчивается расширением .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);

Ответ 6

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

Также заголовок определяет пользовательский интерфейс, который интересует пользователя класса. Кроме того, если вы развернули код как библиотечный или объектный код, заголовок является единственным источником, к которому пользователь будет иметь доступ.