Лучшая практика для комментария функции C++

Ничего не будет "официально" поддерживаться, потому что за C ++ не стоит компания.

Как видите, doxygen поддерживает множество различных блоков http: //www.doxygen.nl / docblocks.html

Лично я предпочитаю придерживаться других рекомендаций. Я стараюсь придерживаться лучших практик javadoc.

Я думаю, что не существует такого понятия, как «лучший» стиль. Вам следует использовать тот, который вам подходит. Он сильно зависит от цели кода. Больше всего в таких комментариях нуждаются API публичных библиотек. С другой стороны, частные методы классов реализации, вероятно, могут полагаться только на самодокументирование, поскольку отсутствие комментариев обычно лучше, чем неправильные / устаревшие комментарии.

Между прочим, Doxygen поддерживает несколько стилей, и Javadoc является одним из них.

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

Лично я ненавижу doxygen и тому подобное, потому что это противоречит моему первому слову. «Документация», если ее можно так назвать, - это просто предварительно заданный заголовочный файл. А стоимость? Почти дублированный код, навязчивые комментарии (серьезно, это удваивает высоту всего) и просто боль.

Ваш код должен быть самодокументированным: используйте описательные имена, разложите все на четко определенные задачи и т. Д. Единственными комментариями должны быть вещи, которые могут нуждаться в разъяснении.

Например, отрывок из класса сетевых сокетов, который я написал:

const bool socket_connected(void) const;

Вы уже знаете, что делает эта функция; Мне не нужно это объяснять. Мне действительно нужно добавить большой кусок комментария, объясняющий, что он возвращает логическое значение (да), которое будет указывать на то, что сокет подключен (да)? Нет. Doxygen просто возьмет мой заголовок и добавит к нему какую-нибудь причудливую таблицу стилей.

Вот пример, где может быть полезно небольшое примечание (создание этого класса):

struct fancy_pants
{
    // doesn't transfer ownship, ensure foo stays alive
    fancy_pants(foo&);
};

Теперь ясно, что мне нужно убедиться, что переданный мной foo не выходит за рамки. Это не потребовало искажения моего кода. Если я собираюсь писать документацию, она должна быть написана мной, с описанием обоснования, предполагаемого использования, "ошибок", примеров и т. Д. Как Boost.

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

/*-------------------------------------------------------
                    <copyright notice>

Determine if two types are the same. Example:

template <typename T, typename U>
void do_something(const T&, const U&, bool flag);

template <typename T, typename U>
void do_something(const T& t, const U& u)
{
    do_something(t, u, is_same<T,U>::value);
}

---------------------------------------------------------*/

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

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

Вы можете использовать Google Style для комментирования.

Типы вещей, которые следует упомянуть в комментариях при объявлении функции:

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

• Может ли какой-либо из аргументов иметь значение NULL.

• Если есть какие-либо последствия для производительности того, как функция используется.

• Если функция повторяется. Каковы предположения о синхронизации?

Есть ряд советов для комментирования, настолько много, что для них есть целая глава в Code Complete . Обратите внимание, что стиль Javadocs и Doxygen также предназначен для автоматической генерации документации. То, что они поощряли, обычно нормально.

Вот несколько советов, которые я считаю важными:

1. Комментарии должны описывать, почему, а не то, что вы делаете.

2. Комментарии должны быть в форме, удобной для поддержки и ввода. Никаких вычурных заголовков и иллюстраций в формате ascii, пожалуйста!