Що потрібно включити до заголовка документації для мого класу

Я шукаю формат документації інформативного класу для моїх класів Entity, Business Logic та Access Access.

Я знайшов два таких форматів з тут

Формат 1

///-----------------------------------------------------------------
///   Namespace:      <Class Namespace>
///   Class:          <Class Name>
///   Description:    <Description>
///   Author:         <Author>                    Date: <DateTime>
///   Notes:          <Notes>
///   Revision History:
///   Name:           Date:        Description:
///-----------------------------------------------------------------

Формат 2

// ===============================
// AUTHOR     :
// CREATE DATE     :
// PURPOSE     :
// SPECIAL NOTES:
// ===============================
// Change History:
//
//==================================

Я відчуваю, що наступні - це основні елементи

• Автор
• Дата створення
• Опис
• Історія редагування

так як ім’я простору імен і класу все одно знайдуться.

Будь ласка, повідомте мені ваші думки, який формат рекомендується та чи є стандартний спосіб написання ревізійної історії?

Більшість інформації, яку ви запропонували там, знайдеться у вихідному сховищі.

Єдине, що вам дійсно потрібно, - це цільовий розділ, в якому йдеться про те, для чого клас.

Чи було б нудно шукати в сховищі кожен раз, коли ви хочете дізнатися іншу інформацію? Я б сказав, що ні. Як часто вам байдуже, хто був оригінальним автором? Або коли файл був створений вперше? Плагіни (наприклад, Ankh SVN для Visual Studio) часто дозволяють клацати правою кнопкою миші у вашому поточному файлі та переглядати журнал репозиторію для цього файлу, тому реально бачити цю інформацію не так вже й багато клопоту.

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

Мають описові назви класів, методів та змінних . Це позбавить від необхідності таких коментарів, як мета та опис. Іноді ми думаємо, що чим коротше назва методу, тим краще. Навпаки, зробіть назву методу стільки, скільки вам потрібно, доки він чітко описує його призначення. Майте лише нотатки, які абсолютно життєво важливі та допомагають зрозуміти код якось певним чином. Внесення змін до коду програмісти часто забувають оновлювати коментарі. Ви можете закінчити, що коментарі та код не синхронізуються і приносять більше шкоди, ніж користі.

Прочитайте цю статтю Джеффа Етвуда - Кодування без коментарів .

Я використовую стандартні теги для створення документації. Нічого більше, нічого менше. Дивіться тут

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

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

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

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

Якщо мені доведеться прочитати ваш "Опис", щоб зрозуміти, чим займається ваш клас, то або (а) ваш назвав його погано, або (б) ви написали поганий клас, який робить занадто багато (SRP).

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

• Опис - що робиться за кодом.
• Примітки. Все, що потрібно знати про код, який легко отримати з коментарів у самому коді.
• Посилання - будь-які посилання, від яких залежить код, не з'ясовуються при використанні includeабо подібних операторах.

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

Більшість інших відповідей, які я прочитав до цих пір, припускають, що є лише одне сховище, яке завжди доступне

Оскільки вихідний код може втратити з'єднання з сховищем (тобто якщо його скопіювати), документація мого класу має такий вигляд:

• class documentation header (= блок коментарів на початку файлу) містить лише необхідні юридичні відомості (тобто авторські права xyz під gpl-ліцензією)
• все, що повинен знати розробник, який використовує клас, повинен перейти до класу-java-doc-comments (або його еквівалент .net), щоб сучасні ідеї могли показувати цю інформацію як інформацію підказки у вихідному коді, що використовує клас.

Ви також можете додати номер квитка для виправлення помилок або особливості запиту, щоб у вас виникли підказки, де / коли / чому створений клас (якщо вам пощастило, що ви можете все-таки отримати доступ до квитків через кілька років).

Коли бджіл попросив виправити проблеми у старих спадкових програмах із закритим джерелом, номери квитків, де для мене досить цінні для розуміння початкових вимог коду.