Лучшее место для документирования нашего кода C ++

Question

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

Какова лучшая практика в этом отношении.

Answer 1

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

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

/**
    This function does stuff with a prime number.  */
void do_stuff(int prime);

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

/**
    This function does stuff with a prime number.
    \param prime A prime number. The function must receive only primes, it
    does not check the integer it receives to be prime.
                                                                               */
void do_stuff(int prime);

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

Answer 2

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

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

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

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

Answer 3

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