Ответ 1
Я помещаю комментарии, описывающие, что делает функция в заголовке и комментарии, описывающие, как это делается в файле cpp.
Итак... Я понимаю, что это может быть субъективным, но мне бы хотелось, чтобы некоторые мнения о том, что лучше всего подходит для этого.
Скажем, у меня есть следующий заголовок и файл .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
Я помещаю комментарии, описывающие, что делает функция в заголовке и комментарии, описывающие, как это делается в файле cpp.
Я склонен использовать 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
, который будет прокомментирован о том, как он достигает этой цели.
В порядке важности:
Если это часть существующего проекта и существует преобладающий стиль комментариев, используйте это. Согласованность в кодовой базе важнее, чем предпочтение отдельного разработчика.
Если это новый проект, используйте Doxygen или аналогичный документ для вашего кода. Хотя это не отвечает на ваш вопрос, так как вы можете использовать оба стиля вместе с ним. Запустите его в ночное время, чтобы у вас была обновленная исходная документация, доступная для просмотра.
Лично я предпочитаю ставить только краткое однострочное резюме встроенных функций и членов в заголовочных файлах, так как в противном случае ему становится труднее получить краткий обзор функциональности класса при проскальзывании через файл заголовка, Подробные описания я оставляю для файла .cpp. Некоторые аксессоры я не комментирую, если их цель действительно очевидна.
У меня также есть большой головокружение о ленивых комментариях, особенно однострочные:
например. Этот комментарий является пустой тратой пространства и может также быть удален:
/** Get the width */
double getWidth();
Этот комментарий полезен:
/** Get the width in inches excluding any margin. */
double getWidth();
Лично я предпочел бы поставить его выше реализации. Я также использовал бы стиль Doxygen, поскольку он дает ту же информацию, но генерирует документацию.
На самом деле это не имеет значения, особенно если вы продолжаете создавать отдельную документацию с помощью doxygen. Пойдите с тем, что ВЫ предпочитаете.
Размещение комментариев в заголовке - лучшее решение. Это происходит потому, что:
Я использую 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
}
Поместить комментарии к функциям в файл заголовка. Это (помимо руководства) первое место, где пользователи вашего класса будут искать документацию. Они не заботятся о реализации, просто о интерфейсе.
Мне нравится использовать условия PRE/POST. Ни один из упомянутых ответов неверен. Только то, что вы/компания предпочитаете. Но условия PRE и POST сообщают вам, каковы входящие/исходящие переменные и как они используются. Это также гарантирует, что вы выполняете какое-то руководство относительно того, как вы собираетесь использовать функцию (предварительные условия), и какие выходы после этой функции (условия сообщения).
В целом, комментарии должны быть рассмотрены аналогичным образом с разделением кода - комментарии, связанные с интерфейсом (например, ваш пример), будут отображаться в заголовке, тогда как комментарии, связанные с реализацией, лучше подходят для файла .cpp.
Если кто-то должен включать ваши классы в свои собственные программы, они должны иметь возможность получать достаточную информацию из файла заголовка, чтобы знать, как использовать класс, не врываясь в саму реализацию. Заголовки комментариев превышают, что, вероятно, не нужно и просто служат для загромождения полезной информации.
Ему нравится спрашивать, что лучше всего подходит для носки. У некоторых инструментов есть больше возможностей для работы, если вы ставите декларацию и комментируете вместе, и это, вероятно, имеет наибольший смысл в отношении того, что ожидают люди. Но комментирование беспорядочно. Особенно важно иметь в/из материала, если у вас нет инструмента, который его использует. Любой программист может видеть то, что ему нужно от декларации, и то же самое относится к языку в целом. Нет ничего более бесполезного, чем комментарии, например//это конструктор.
Скорее старайтесь как можно проще сохранить код с именами, которые имеют смысл и общую организацию для кода, и если есть что-то странное, напишите настоящий абзац о нем, как // Мы должны были это сделать, потому что некоторые странные api, которые мы используем, требуют определенных вещей // это заставило некоторые другие вещи сломаться, и звонки на него иногда оптимизируются // поэтому не вынимайте эти вызовы методов или оптимизатор оптимизирует // некоторые другие вещи и вся программа перестает работать
Назначение в заголовке, контракт над функцией implementaiton, почему в теле функции.
Это требует либо доставки .cpp, либо для использования инструмента, такого как doxygen, чтобы опубликовать документацию.
Преимущество во время зависимостей: улучшенная документация не повлияет на зависимости заголовков.
В любом случае, выберите стиль и будьте последовательны
Лучшая практика - это то, что стандарт для организации, для которой написан код.
Если это только для меня:
Назначение и использование функции в заголовке, функции в реализации.
Поскольку я всегда использовал Visual Assist X и имею возможность легко переключаться с кодом, я использую заголовочный файл как индекс. То есть заголовочный файл содержит только соответствующие данные без каких-либо дополнительных комментариев, а не для добавления раздувания в файл. Если читатель хочет получить дополнительную информацию о функции, они могут перейти на cpp.
Это, конечно, предполагает, что все люди, которые читают ваш код, будут иметь один и тот же процесс мышления, который является ложным. Приятно иметь только раздувание в одном файле.
Внутри функции вы можете поместить комментарий в ту же строку, что и открывающая скобка.
/* what is this function for, and so on. Stuff the caller needs to know. */
foo ()
{ // pre-condition
}
Я видел, что это рекомендовано в качестве места для перечисления предварительных условий. Я пробовал это и нашел это довольно тесно, потому что я склонен писать подробные комментарии. Кроме того, предварительное условие - это то, о чем должен знать абонент, и он не должен затеряться внутри тела функции.
В противном случае, я всегда стараюсь поместить общие описания функции вне ее и объяснения, почему она закодирована так, как она находится внутри функции, рядом с кодом. Так что в целом согласны с стилем промоутеров Doxygen.