Як боротися з тавтологією в коментарях? [зачинено]

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

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

(C # приклад, але зверніться до цього питання як до мови-агностика).

Подібний коментар марний; що я роблю неправильно? Чи неправильний вибір імені? Як я міг краще прокоментувати такі частини? Чи варто просто пропустити коментар до таких речей?

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

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

Особливо враховуючи використання Visual Studio коментарів, що супроводжують IntelliSense , непогано почати з короткої інформації про поле:

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

І тоді, продовжуючи кодувати, коли ви не можете згадати, чи UpdateLocationбуло місце, де відбулося оновлення, чи місце, до якого оновлення надсилається, вам доведеться переглянути код. Саме в цей момент ви повинні додати цю додаткову інформацію:

class Example
{
    /// <summary>
    /// The Uri location where the update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

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

Яке оновлення слід Example.UpdateLocationвикористовувати для зберігання?

class Example
{
    /// <summary>
    /// The Uri location where the Foo update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

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

І так само, як програмування, ваші коментарі повинні починатися десь. Тавтологічні коментарі - це Hello World!коментарі, коли ви практикуєте писати та оновлювати документацію, ваша стартова документація стане все більш стійкою.

Коментарі ніколи не повинні дублювати ваш код. Коментарі не повинні відповідати на питання " як? ", А лише " чому? " Та " що? ". Чому обраний такий алгоритм, які тут неявні припущення (якщо ваша мова не є достатньо потужною, щоб виразити його системою типів, контрактами тощо), що взагалі є причиною цього робити тощо.

Я рекомендую для натхнення поглянути на практику грамотного програмування.

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

Залиште їх!

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

Покладіть їх!

Ваш приклад ілюструє два винятки з цього правила:

По-перше, "UpdateLocation" може бути (залежно від контексту) неоднозначним. У такому випадку вам або потрібно дати йому кращу назву або надати коментар, щоб усунути неоднозначність. Удосконалення імені, як правило, є кращим варіантом, але це не завжди можливо (наприклад, коли ви реалізуєте опублікований API).

По-друге, "///" в C # вказує коментар, який призначений для автоматичного генерування документації. IDE використовує ці коментарі для підказки щодо інструментів, і є інструменти (Sandcastle), які можуть генерувати довідкові файли тощо з цих коментарів. Таким чином, є аргументи для вставки цих коментарів, навіть якщо методи, які вони документують, вже мають описові назви. Вже тоді багато досвідчених розробників нахмуриться від дублювання інформації. Вирішальним фактором повинні бути потреби тих, для кого документація призначена.

Я категорично не згоден з відповідями "не пишіть коментарів". Чому? Дозвольте зазначити, трохи змінивши ваш приклад.

public Uri UpdateLocation ();

Отже, що робить ця функція:

• Повертає це "місце оновлення"? або
• Чи "оновить" місцеположення та повертає нове місцеположення?

Видно, що без коментаря є неоднозначність. Новачок легко може помилитися.

У вашому прикладі це властивість, тому методи "get / set" виявляють, що другий варіант невірний і він дійсно означає "оновити місце", а не "оновити місцезнаходження". Але зробити цю помилку занадто просто, особливо у випадках неоднозначних слів, таких як "оновлення". Грай безпечно. Не плутайте когось нового з цим лише для того, щоб заощадити кілька секунд вашого часу.

/// <summary>блоки використовуються для створення документації для документації IntelliSense та API .

Таким чином, якщо це загальнодоступний API, ви завжди повинні включати принаймні <summary>коментар, навіть якщо мета функції має бути зрозумілою для читачів.

Однак це виняток із правила; в загальному, тільки НЕ забудьте DRY (не повторюватися) .

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

_{Для мене випадок явної вигоди був тоді, коли була автоматизована перевірка відсутніх коментарів, і я використовував цю перевірку для виявлення коду, де потрібно заповнити важливу інформацію; для цього я справді заповнював деякі заповнювачі - просто щоб переконатися, що звіт про інструменти не містить "помилкових тривог".}

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

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

class Example
{
    /// <summary>
    /// Self descriptive method name.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

_{Прикладом, коли я міг би використовувати описані вище наповнювачі, будуть коментарі Javadoc, яким потрібні виділені поля для повернення значення, параметрів та виключень. Досить часто я вважаю, що має сенс описати більшість або навіть все це в одному підсумковому реченні, метод, який повертає <опишіть, що повертається> для заданих параметрів <опишіть параметри> . У таких випадках я заповнюю формально обов'язкові поля з простим див. Вище , вказуючи читача на короткий опис.}

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

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

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

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

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

Суть полягає в наступному: Подумайте про майбутнє. Запитайте себе, що є важливим і очевидним для вас, як програма повинна розумітись і змінюватися в майбутньому. [1]

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

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

[1] Це виходить за рамки питання коментарів, але це варто піднести: Якщо ви виявите, що у вас є чітке уявлення про те, як міг змінитися ваш код у майбутньому, вам, ймовірно, варто задуматися над тим, щоб просто зробити коментар і вбудувати ці параметри. всередині самого коду, оскільки це майже завжди буде більш надійним способом забезпечити надійність майбутніх версій вашого коду, ніж намагатися використовувати коментарі, щоб направити якусь невідому майбутню людину в правильному напрямку. У той же час ви також хочете уникати надмірної генералізації, оскільки люди, як відомо, погано прогнозують майбутнє, і це включає майбутнє змін програми. Отже, спробуйте визначити та зафіксувати розумні та добре перевірені аспекти майбутнього на всіх рівнях дизайну програми, але не варто '

У своєму власному коді я часто залишаю на місці тавтології коментарів, включаючи такі, що викликають жахливість, як-от:

<?php
// return the result
return $result;
?>

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

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

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

<?php
//get the id of the thing
$id = $_POST['id'];

//query the things out of the the database
$things = array();
$result = mysql_query("SELECT * FROM Things WHERE `id` = $id");
while ($row = mysql_fetch_assoc($result)) {
    //create a proper Thing object or whatever
    $things[] = new Thing($row);
}

//return the things
return $things;
?>

(Ігноруйте неповний код, ін'єкції SQL тощо. Ви отримуєте ідею.)

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

Коментарі можна використовувати для виконання одного з наступних дій.

1. Інформація для генераторів документів для захоплення. Це не можна занижувати, це надзвичайно важливо.
2. Попередження, чому фрагмент коду є таким, яким він є, та які інші міркування. Я мав справу з кодом, написаним двома мовами програмування. Однією з ключових частин цього було створення спільної структури між двома мовами. Коментар в обох місцях, в якому повідомляється користувач, що якщо вони змінить цю кількість, вони також повинні змінити інше, є надзвичайно корисним.
3. Напишіть замітки, щоб пояснити, чому такий дивний фрагмент коду є таким, яким він є. Якщо вам довелося подумати над тим, як змусити фрагмент коду працювати певним чином, і рішення не очевидно з самого початку, напевно, варто пояснити, що ви намагалися зробити.
4. Позначення входів / виходів, якщо вони не зрозумілі. Завжди добре знати, які очікуються ваші входи та в якому форматі вони є.

Коментарі не слід використовувати для наступного:

1. Поясніть надзвичайно очевидні речі. Я коли - то бачив успадкований код , як це: page=0; // Sets the page to 0. Я думаю, що будь-яка компетентна особа могла це зрозуміти.

Я б видалив тавтологію, але зберігаю коментар, я б коментував властивості та назви змінних, надаючи вибіркове значення, щоб використання було чітко зрозуміло:

property UpdateLocation:TUpdateLocation;  // url="http://x/y/3.2/upd.aspx",proto=http

Тепер я точно знаю, що там йде, і з коментаря я маю чітке уявлення, як ним користуватися.

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

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

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

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

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

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

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

Чим менше коментарів вимагає ваш код, тим краще код!

Подібний коментар марний; що я роблю неправильно?

Це видається марним лише тоді, коли ви вже знаєте, що UpdateLocationробить. Чи є тут "оновлення" дієсловом чи іменником додаток? Тобто це щось, що оновлює місцеположення, чи це місце оновлення? Можна сказати про останнє з того, що UpdateLocation, мабуть, є властивістю, але важливішим є те, що іноді не заважає прямо заявити щось, що здається очевидним.

Автоматично складена документація вбік, код повинен документувати сам, так що коментарі повинні документувати лише там, де коду недостатньо для документування.

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