Doxygen, слишком тяжелый для поддержания?

Ответ 1

Является ли синтаксис Doxygen сложным? Или это факт, что вы должны прокомментировать все функции сейчас.

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

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

• Что делает функция
• Параметры
• Коды возврата
• Любые основные предупреждения/ограничения в отношении функции.

Это верно независимо от используемого инструмента документации.

Мой большой совет: Избегайте соблазна слишком много комментировать. Опишите, что вам нужно, и не более того. Doxygen дает вам множество тегов, но вам не нужно их использовать.

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

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

Ответ 2

Сложно что-то не так в том, как вы используете комментарии или как вы развиваетесь.

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

Если вы используете doxygen для документирования внутреннего потока функций, вам следует, возможно, пересмотреть этот подход (и даже тогда эти комментарии не должны сильно меняться). Когда у вас есть функция, которая вычисляет некоторое значение, тогда комментарий /// Calculating xy using the abc algorithm определенно является тем, что не должно меняться каждый день.

Ответ 3

Я чувствую, что вы возвращаете то, что вы вкладываете в комментарии, 5 минут, комментируя класс, будет через 3 месяца, когда класс должен быть изменен кем-то другим, кроме оригинального автора (действительно, иногда оригинальным автором) гораздо меньше времени, чтобы справиться с ними.

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

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

Ответ 4

Это зависит от того, сколько информации вы указали в своей документации.

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

Советов:

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

Вы будете рады, когда придете редактировать свой код через 6 месяцев...

Ответ 5

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

Ответ 6

Не совсем то, что вы ищете, но этот плагин Vim может генерировать заглушку Doxygen поверх ваших определений. Это работает очень хорошо.

Ответ 7

Судите сами, если стиль ниже соответствует вашим потребностям. Это C-аффинный tho, но, возможно, вы можете извлечь из него достаточно для своих целей.

///\file

/// Brief description goes here
bool /// @retval 0 This is somewhat inconsistent. \n Doxygen allows several retval-descriptions but 
     /// @retval 1 will not do so for parameters. (see below)
PLL_start( 
   unsigned char busywait, ///< 0: Comment parameters w/o repeating them anywhere. If you delete this param, the
                           ///     comment will go also. \n
                           /// 1: Unluckily, to structure the input ranges, one has to use formatting commands like \\n \n
                           /// 2-32767: whatever
   int param)              ///< 0: crash \n
                           ///  1: boom \n
                           ///  2: bang!
{
   /**
    * Here goes the long explanation. If this changes frequently, you have other more grave problems than 
    * documentation. NO DOCUMENTATION OF PARAMETERS OR RETURN VALUES HERE! REDUNDANCY IS VICIOUS!
    * - Explain in list form.
    * - It really helps the maintainer to grok the code faster.
    *
    *@attention Explain misuses which aren't caught at runtime.
    *
    *@pre Context:
    * - This function expects only a small stack ...
    * - The call is either blocking or non-blocking. No access to global data. 
    *
    *@post The Foobar Interrupt is enabled. Used system resources:
    *    - FOO registers 
    *    - BAR interrupts
    */
    /**@post This is another postcondition. */
}

Ответ 8

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

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

Ответ 9

В дополнение к Doxygen я думаю, вам стоит взглянуть на Code Rocket.

Он фактически документирует то, что происходит внутри ваших методов, травля через фактический код и комментарии, которые они содержат, поэтому не ограничивается только заголовками комментариев функций, которые могут устареть с тем, что на самом деле существует. /p >

Он автоматически предоставит вам блок-схему и псевдокодную визуализацию содержимого вашего метода в виде документации.

Ответ 10

Используйте сильные стороны Doxygen - он будет генерировать описания классов и методов без добавления комментариев (только не по умолчанию - установите EXTRACT_ALL = YES).

Я не документирую каждый параметр, потому что я думаю, что их имена должны делать это для них (*).

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

Я хочу, чтобы комментарии были значимыми - если я увижу комментарий, он выделяется, и я обращу внимание.

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