Дослідження прибутків / втрат продуктивності документації на коди

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

ЩО ЗНАЄТЬСЯ:

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

АЛЕ:

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

ПИТАННЯ:

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

Я шукаю тематичні дослідження або відповіді, які можуть принести об'єктивні докази, що підтверджують зроблені висновки.

Спасибі заздалегідь!

Стаття "Типографічний стиль - це більше, ніж косметичний" - досить стара, але дуже цікава: http://portal.acm.org/citation.cfm?id=78611 .

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

Для тих, хто, як я, не має доступу до цифрової бібліотеки ACM, вони створили дві групи програмістів і дали їм однаковий код для вивчення. Група А отримала лише код із звичайними коментарями, група В отримала чудовий друкований список із змістом, перехресними посиланнями та всіма смаками, які були можливі ще в 1990 році.

Потім вони попросили дві групи виконати певні завдання над кодом (наприклад, розширити функцію, знайти помилку, ...) і оцінили їх за швидкістю та якістю відповідей.

Щоб збалансувати групу, у них була однакова кількість експертів та молодших програмістів.

Що ж, виявилось, що група B (та з досить друкованим списком) стійко набрала кращий результат, ніж група А в численних тестах. І, в конкретних випадках, лише найекспертнішим групи А вдалося перевершити молодшого програміста групи В.

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

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

Я не можу це підкріпити жодними вагомими доказами, крім ну, здорового глузду.

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

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

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

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

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

Рішення про те, чи є даний метод, без інструментів, які, мабуть, ще не винайдені, занадто суб'єктивне, щоб вимагати написання документації.

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

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

(Тісно пов'язане: Чи може бути занадто багато однаковості в стандартах кодування? )

^{Вибачте, що я не маю жодного цитування досліджень, але я підозрюю, що це проблема, коли будь-які спроби виміряти це надто сильно вплинуть на результат, щоб зробити загальні висновки.}

Я думаю, що нам потрібно відокремити "звичайний" код від публічних API в цьому відношенні. Щодо звичайного коду, я твердо погоджуюся з більшістю інших відповідників у цьому коді, слід самостійно документувати і читати майже як прозу . Якщо мій код не такий, як правило, я винен, тому замість документування його слід переробити. Невеликі методи, які одночасно виконують лише одне, працюючи на одному рівні абстракції, мають правильне та описове ім'я , можуть стати чудовим шляхом до досягнення цього.

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

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

Навчальна робота з цієї теми - Чистий кодекс .

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

Проблема полягає в тому, чи ви економите час, документуючи свій код проти кожного наступного розробника, який повинен спробувати розібратися, що це робить. Якщо ваш код летить за допомогою перегляду коду, але ніхто не викликає запитань щодо того, що він робить, ви, ймовірно, в хорошій формі. Не надто важко описати припущення, які ви робите щодо внесків. Скажімо, ваш метод бере цілий об'єкт і повертає рядовий об'єкт. Чи може int бути нульовим? Чи є значення min / max (крім integer.MinValue / MaxValue)? Чи може він повернути порожній рядок або нуль? Це кидає якісь винятки? Звичайно, кожен може знайти їх за допомогою інспекції, але якщо достатньо інших розробників буде використовувати ваш код, заощадження кожні кілька хвилин цілком вартує вашого часу. Крім того, він дає змогу тестерам створити тести для підтвердження коду.

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

Таким чином, код повинен бути дуже добре прокоментований, і таким чином повинен бути самодокументований код, який не вимагає жодної зовнішньої документації.

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

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

Дивіться « Чистий код» та PPP від Bob Martin для більш глибокої дискусії.