Чи потрібно написати коментар javadoc для параметра «КОЖНЕ» у підписі методу?

Один із розробників моєї команди вважає, що потрібно написати коментар javadoc для параметра КОЖНО у підписі методу. Я не думаю, що це потрібно, і насправді я думаю, що це може бути навіть шкідливим.

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

Але я думаю, що це зайве для кожного параметра. Якщо вже очевидно, для чого цей параметр, коментар javadoc є зайвим; ви просто створюєте додаткову роботу для себе. Крім того, ви створюєте додаткову роботу для тих, хто має підтримувати свій код. Методи змінюються з часом, а підтримка коментарів майже так само важлива, як підтримка коду. Скільки разів ви бачили коментар на кшталт "X робить Y з причини Z" лише для того, щоб побачити, що коментар застарів, і насправді метод більше навіть не приймає параметр X? Це відбувається постійно, бо люди забувають оновлювати коментарі. Я б заперечував, що оманливий коментар шкідливіший, ніж взагалі ніякий коментар. Таким чином, є небезпека надмірного коментування: створивши непотрібну документацію, ви

Однак я поважаю іншого розробника в своїй команді і приймаю, що, можливо, він правий, і я помиляюся. Ось чому я ставлю своє питання до вас, колеги-розробники: чи дійсно потрібно написати коментар javadoc для ВСЕГО параметра? Припустимо, що код є внутрішнім для моєї компанії, і його не використовуватиме жодна сторона.

Анотації Javadoc (і, в слові Microsoft, XMLDoc) - це не коментарі , це документація .

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

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

Назви аргументів / параметрів ніколи не роз'яснюються. Ви завжди думаєте, що вони є, коли ви провели минулий день, працюючи над кодом, але спробуйте повернутися до нього після 2-тижневої відпустки, і ви побачите, наскільки вони насправді не справжні.

Не розумійте мене неправильно - важливо вибрати змістовні імена для змінних та аргументів. Але це стосується коду, а не документації. Не сприймайте фразу «самодокументування» занадто буквально; що мається на увазі в контексті внутрішньої документації (коментарі), а не зовнішньої документації (контрактів).

Або коментуйте все, або нічого не коментуйте (очевидно, коментуючи все - це набагато кращий вибір). Подумайте про те, хто використовує ваш код, або перегляньте ваш API безпосередньо у вихідному файлі або в створеному файлі doc (тобто доксигенному виведенні). Невідповідності, як правило, призводять до плутанини, що призводить до часу, витраченого на перекопування джерела, щоб з'ясувати, чому щось не було прокоментовано, що призводить до втрати часу, якого можна було б уникнути, якби параметр просто коментувався в першу чергу.

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

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

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

Отже, це означає, що розробники не повинні витрачати час на документування очевидних параметрів та повернення значень, правда?

Що ж, давайте розбимо його.

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

Якщо ми обираємо і обираємо, то витрати такі:

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

Отже, я схильний би просто документувати все. Мінус певний, але міститься.

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

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

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

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

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