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

Ответ 1

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

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

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

Например, выдержка из класса сетевого сокета я написал:

const bool socket_connected(void) const;

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

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

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

Теперь ясно, что я должен убедиться, что foo, который я передаю, не выходит за рамки. Это не требовало угашения моего кода. Если я собираюсь написать документацию, это должно быть написано мной, описывая логику, предполагаемое использование, "getcha", примеры и т.д. Подобно 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);
}

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

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

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

Ответ 2

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

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

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

Ответ 3

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

Типы заметок в комментариях в объявлении функции:

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

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

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

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

Ответ 4

Я придерживаюсь Visual С++ Documentation Tags MSDN рекомендует. Я вижу MSDN в качестве официальной документации.

Пример:

/// <summary>Sorts the list to by the given column</summary>
/// <param name="sel">Column to be sorted (index-1-based) and sort direction (pos. = ascending)</param>  
/// <returns>Documentation of return type</returns>  
void CExamlist::SetSorting(int sel) { ... }

Получает интерпретацию ReSharper С++ на

Visual Studio 2012+ будет интерпретировать эти комментарии также в соответствии с Как написать комментарии С++, которые отображаются в Intellisense?

CppTripleSlash - отличный бесплатный плагин VS, который добавляет правильные теги XML после ввода "///". Эта функция портируется из редактора Visual Studio С#.

Ответ 5

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

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

Ответ 6

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

Некоторые советы, которые я считаю важными, следующие:

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

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

Ответ 7

Помимо стандартов Google, я нашел это руководство здесь Эдвард Пэрриш, чтобы быть очень полезным!

Например, комментарии блока:

/**
    CS-11 Asn 2
    checks.cpp
    Purpose: Calculates the total of 6 checks

    @author Ed Parrish
    @version 1.1 4/10/16 
*/

или комментарии к коду функции:

/**
    Encodes a single digit of a POSTNET "A" bar code.

    @param digit the single digit to encode.
    @return a bar code of the digit using "|" as the long
    bar and "," as the half bar.
*/

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