Куди покласти блоки коментарів до кисню для внутрішньої бібліотеки - у H або у файлах CPP? [зачинено]

Здоровий глузд підказує, що блоки коментарів Doxygen повинні бути розміщені у заголовкових файлах, де знаходяться класи, структури, перелічення, функції та оголошення. Я погоджуюсь, що це слушний аргумент для бібліотек, які мають намір розповсюджуватись без їх джерела (лише заголовки та бібліотеки з об’єктним кодом).

АЛЕ ... Я думав про прямо протилежний підхід, коли розробляв внутрішню для компанії (або як допоміжний проект для себе) бібліотеку, яка буде використовуватися з повним вихідним кодом. Я пропоную розмістити великі блоки коментарів у файлах реалізації (HPP, INL, CPP тощо), щоб НЕ захаращувати інтерфейс класів та функцій, оголошених у заголовку.

Плюси:

• Менше захаращення файлів заголовків, можна додати лише категоризацію функцій.
• Блоки коментарів, які попередньо переглядаються, коли використовується, наприклад, Intellisense, не стикаються - це дефект, який я спостерігав, коли у мене є блок коментарів для функції у файлі .H і його вбудоване визначення в тому ж файлі .H але включено з файлу .INL.

Мінуси:

• (Очевидний). Блоки коментарів відсутні у файлах заголовків, де знаходяться декларації.

Отже, що ви думаєте і, можливо, пропонуєте?

Покладіть документацію, де люди будуть читати та писати її, коли вони використовують та працюють над кодом.

Коментарі до класу йдуть перед класами, коментарі до методів - перед методами.

Це найкращий спосіб забезпечити підтримку речей. Крім того, файли заголовків залишаються відносно м’якими та уникають зворушливих проблем, пов’язаних із оновленням документів методів, що спричиняє забруднення заголовків та ініціює відновлення. Я насправді знав, що люди використовують це як привід для подальшого написання документації !

Я люблю користуватися тим фактом, що імена можуть бути задокументовані в різних місцях.

У файлі заголовка я пишу короткий опис методу та документую всі його параметри - вони менш імовірно зміняться, ніж реалізація самого методу, і якщо вони це роблять, тоді прототип функції в будь-якому випадку потрібно змінити .

Я розміщу документацію довгоформатного формату у вихідних файлах поруч із фактичною реалізацією, тому деталі можна змінювати в міру розвитку методу.

Наприклад:

mymodule.h

/// @brief This method adds two integers.
/// @param a First integer to add.
/// @param b Second integer to add.
/// @return The sum of both parameters.
int add(int a, int b);

mymodule.cpp

/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
  return b + a;
}

Наявність коментарів у заголовку означає, що всі користувачі класу повинні бути перекомпільовані, якщо коментар змінено. Для великих проектів кодери будуть менш схильні оновлювати коментарі в заголовках, якщо вони ризикують витратити наступні 20 хв на відновлення всього.

І .. оскільки ви повинні читати html-документ, а не переглядати код документації, це не велика проблема, оскільки блоки коментарів важче знайти в вихідних файлах.

Заголовки: Простіше читати коментарі, оскільки при перегляді файлів менше "шуму".

Джерело: Тоді у вас є фактичні функції, доступні для читання під час перегляду коментарів.

Ми просто використовуємо всі глобальні функції, коментовані в заголовках, і локальні функції, коментовані у джерелі. Якщо ви хочете, ви також можете включити команду copydoc, щоб вставити документацію в декількох місцях, не потрібно писати її кілька разів (краще для обслуговування)

Однак ви також можете отримати результати, скопійовані в іншу документацію файлу, простою командою. Наприклад: -

Мій файл1.h

/**
 * \brief Short about function
 *
 * More about function
 */
WORD my_fync1(BYTE*);

МОЙ файл 1.c

/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}

Тепер ви отримуєте однакову документацію щодо обох функцій.

Це дає вам менше шуму у файлах коду, одночасно ви отримуєте документацію, написану в одному місці, представлену в кількох місцях у кінцевому результаті.

Зазвичай я поміщаю документацію для інтерфейсу (\ param, \ return) у файл .h та документацію для реалізації (\ деталі) у файл .c / .cpp / .m. Доксиген групує все в документації щодо функції / методу.

Я помістив усе у файл заголовка.

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

Я використовую QtCreator для програмування. Дуже корисний фокус полягає у натисканні клавіші Ctrl на функцію чи метод для отримання оголошення у файлі заголовка.

Коли метод коментується у файлі заголовка, ви можете швидко знайти потрібну інформацію. Отже, для мене коментарі повинні знаходитись у файлі заголовка!

У c ++ іноді реалізацію можна розділити між заголовком та модулями .cpp. Тут здається чистішим розміщення його документації у файлі заголовка, оскільки це єдине місце, де гарантуються всі загальнодоступні функції та методи.