Документація з кодом: Громадська проти Непублічна?

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

ЯКЩО, розробляючи код бібліотеки для інших людей, я намагаюся вмістити якомога більше документації у файли заголовків; що викликає питання: чи варто документувати методи, які є непублічними, навіть варті часу? Вони не будуть використовувати їх безпосередньо, насправді вони не можуть. У той же час, якщо я поширюю необроблений код (хоча і неохоче), ці непублічні методи будуть видимими і можуть потребувати пояснення.

Просто шукайте деякі стандарти та практики, які ви всі бачите або використовуєте у своїх подорожах.

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

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

Це все, швидше, суб'єктивно.

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

У заголовку класу:

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

У коді реалізації класу:

• локальні декларації так само, як у заголовку
• визначення функцій завжди (повний контракт)
• Визначення функції члена завжди (повний контракт або посилання на корінь віртуальної переоцінки)
• статичні змінні, визначені, якщо такі є (ціль, чому)

У заголовку шаблону:

• вище злиті і
• відповідні / непридатні типи для аргументів шаблону та
• наскільки добре визначається придатність

На private:початку приватного розділу - вся документація, яка потребує користувачів.

Документація коштує будь-якого дня, вона допомагає коротко пояснити випадки використання та історії. Скільки коли-небудь код не роз'яснюється, він не може пояснити бізнес так легко, як лише кілька рядків розповіді про історію. Код, безумовно, вимагає від користувача дотримуватися логіки, щоб зрозуміти, що відбувається. :-) Мої 2 копійки ...

Безумовно!

Цей код повинен бути самодокументованим - це гасло, яким потрібно жити. Тим не менш, я б пішов так далеко, щоб сказати, що приватний код потребує стільки ж документації, якщо не більше, ніж публічного коду, тому що зазвичай тут відбувається найбільше припущень, просто тому, що кодер передбачає, що він залишиться в темряві . Отже, через пару місяців, коли помилка прийде до вас, ви витратите час, намагаючись пригадати, що було за ідею коду (можливо, ви самі).

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