Рекомендации: где следует использовать комментарии в коде C/С++?

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

Скажем, у меня есть следующий заголовок и файл .cpp:

Заголовок:

// foo.h

class foo
{
public:
    int bar(int in);
};

каст:

// foo.cpp

int foo::bar(int in)
{
    // some algorithm here which modifies in and returns the modified value
}

Теперь скажите, что у меня есть этот комментарий функции:

/* 
    input:    an integer as input to algorithm foo

    output:   The result of the algorithm foo on input in

    remarks:  This function solves P = NP
*/

Лучше всего разместить этот комментарий функции в заголовке над объявлением функции или над определением функции в файле cpp? Спасибо SO

ОТВЕТЫ

Ответ 1

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

Ответ 2

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

/**
 * Fills the handler with GIF information
 * 
 * @param filename GIF File name to be loaded
 * @return Inited GIF Handler or NULL for error
 */
pGifHandler gifHandlerLoad(const char* filename);

/**
 * Removes all data used by the GIF handler
 * 
 * @param gifHandler GIF Handler to be destroyed
 * @note This also clears palette and bitmap(s)
 */
void gifHandlerDestroy(pGifHandler gifHandler);

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

Ответ 3

В порядке важности:

  • Если это часть существующего проекта и существует преобладающий стиль комментариев, используйте это. Согласованность в кодовой базе важнее, чем предпочтение отдельного разработчика.

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

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

У меня также есть большой головокружение о ленивых комментариях, особенно однострочные:

например. Этот комментарий является пустой тратой пространства и может также быть удален:

/** Get the width */
double getWidth();

Этот комментарий полезен:

/** Get the width in inches excluding any margin. */
double getWidth();

Ответ 4

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

На самом деле это не имеет значения, особенно если вы продолжаете создавать отдельную документацию с помощью doxygen. Пойдите с тем, что ВЫ предпочитаете.

Ответ 5

Размещение комментариев в заголовке - лучшее решение. Это происходит потому, что:

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

Ответ 6

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

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

Заголовок:

// foo.h

class foo
{
public:
    /**\brief This function solves P = NP */
    int bar(int in);
};

каст:

// foo.cpp

/** 
 \param[in]    an integer as input to algorithm foo

 \returns    The result of the algorithm foo on input in
*/
int foo::bar(int in)
{
    // some algorithm here which modifies in and returns the modified value
}

Ответ 7

Поместить комментарии к функциям в файл заголовка. Это (помимо руководства) первое место, где пользователи вашего класса будут искать документацию. Они не заботятся о реализации, просто о интерфейсе.

Ответ 8

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

Ответ 9

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

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

Ответ 10

Ему нравится спрашивать, что лучше всего подходит для носки. У некоторых инструментов есть больше возможностей для работы, если вы ставите декларацию и комментируете вместе, и это, вероятно, имеет наибольший смысл в отношении того, что ожидают люди. Но комментирование беспорядочно. Особенно важно иметь в/из материала, если у вас нет инструмента, который его использует. Любой программист может видеть то, что ему нужно от декларации, и то же самое относится к языку в целом. Нет ничего более бесполезного, чем комментарии, например//это конструктор.

Скорее старайтесь как можно проще сохранить код с именами, которые имеют смысл и общую организацию для кода, и если есть что-то странное, напишите настоящий абзац о нем, как // Мы должны были это сделать, потому что некоторые странные api, которые мы используем, требуют определенных вещей // это заставило некоторые другие вещи сломаться, и звонки на него иногда оптимизируются // поэтому не вынимайте эти вызовы методов или оптимизатор оптимизирует // некоторые другие вещи и вся программа перестает работать

Ответ 11

Назначение в заголовке, контракт над функцией implementaiton, почему в теле функции.

Это требует либо доставки .cpp, либо для использования инструмента, такого как doxygen, чтобы опубликовать документацию.

Преимущество во время зависимостей: улучшенная документация не повлияет на зависимости заголовков.

В любом случае, выберите стиль и будьте последовательны

Ответ 12

Лучшая практика - это то, что стандарт для организации, для которой написан код.

Если это только для меня:

Назначение и использование функции в заголовке, функции в реализации.

Ответ 13

Поскольку я всегда использовал Visual Assist X и имею возможность легко переключаться с кодом, я использую заголовочный файл как индекс. То есть заголовочный файл содержит только соответствующие данные без каких-либо дополнительных комментариев, а не для добавления раздувания в файл. Если читатель хочет получить дополнительную информацию о функции, они могут перейти на cpp.

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

Ответ 14

Внутри функции вы можете поместить комментарий в ту же строку, что и открывающая скобка.


/* what is this function for, and so on.  Stuff the caller needs to know. */
foo ()
{       // pre-condition
}

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

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