Useless коментарі до коду: які писати не варто і чому

Вітання, мене звати Сергій Сохромов і я — проєктний менеджер в AMC Bridge. Позиція PM-а у нашій компанії означає, що я також був Senior-розробником, а відтак з власної практики знаю технічну складову розробки програмного забезпечення. За 15 років в ІТ, я бачив різний код і різні коментарі до коду, тож вважаю цю тему важливою для обговорення.

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

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

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

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

Для чого писати коментарі в коді

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

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

Але писати хороший код не достатньо. Є довгий перелік галузей ПЗ, що вимагають написання коментарів за замовчуванням, наприклад: публічний API (Application Programming Interface). Це як публічні інтерфейси класів, так і інтерфейс за зразком REST API та інші API, які використовують зовнішні користувачі. Такий API потребує коментарів з описом того, що API робить, які аргументи приймає, які дані повертає, які винятки генерує тощо.

Наприклад, продуктова компанія з власним R&D писатиме коментарі в коді для того, щоб обслуговувати існуючий софт було дешевше. Натомість сервісна компанія зобов’язана надавати документацію до коду, який вона розробляє, тому у цьому випадку коментарі — це мастхев як один із фінальних артефактів.

Види коментування коду

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

Ми розглянемо документаційні та пояснювальні види коментарів.

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

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

Приклад документаційного коментаря ви можете побачити нижче (використовується мова програмування C++):

/*
fibonacci calculates Fibonacci series using recursion approach.

arg: n (int) - value to be calculated.

returns (int) Fibonacci series value.
*/
int fibonacci(int n) {
    if (n <= 1)
        return n;
    return fibonacci(n - 1) + fibonacci(n - 2);
}

Документаційні коментарі завжди варто писати у конкретно заданому форматі, що може розпарсити IDE (Integrated Development Environment) і автоматичний генератор документації.

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

int fibonacci(int n) {
    //0 and 1 are seed values and equal to 0 and 1 correspondingly
    if (n <= 1)
        return n;
    //run recursion to compute Fibonacci series for the given `n`
    return fibonacci(n - 1) + fibonacci(n - 2);
}

Які коментарі варто писати, а які ні

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

🟢 Варто:

• Copyright-коментарі в шапці файлів вихідного коду. Код завжди комусь належить і потрібно це вказувати.
• Опис інтерфейсу. Інтерфейс публічного REST API, інтерфейс класу з описом публічних методів, опис глобальних констант, якщо в проєкті такі є, опис функцій. Будь-яка функціональність, яку використовують ваші колеги з команди або колеги з інших груп розробки, повинна документуватись так, щоб було зрозуміло, що роблять конкретні функція або метод.
• Опис та пояснення алгоритмів. У випадку використання складних математичних підходів або складних механізмів розгалуження в алгоритмах вашого ПЗ, я рекомендую використовувати коментарі для пояснення кроків виконання функції, для пояснення значень за замовчуванням для перемінних та всього іншого, що допоможе розуміти код.
• Коментарі TODO/FIXME для процесу, що йтиме після розробки — рефакторингу. Завжди бракує часу на те, щоб написати код ідеально. І часто ми робимо просто щоб працювало, та поповнюємо список технічного боргу. Окрім опису завдань у технічному боргу, я рекомендую використовувати визначені вашою командою ключеві слова для опису того, що потрібно зробити на конкретних ділянках коду.

🔴 Не варто:

• Коментарі без змісту. Наприклад, ви пишете перед ініціалізацією змінної «Variable initialization». Цей коментар не дає жодного додаткового значення, його не варто писати. Краще опишіть значення за замовчуванням, яким ви ініціалізуєте змінну.

class Foo {
public:
    Foo() {
        //init variable !!!USELESS
        int i = 1;
    }
};

• Дублювання коміт-повідомлень у заголовках програмного коду. Уявімо, ви робите коміт у систему контролю версій з пояснювальним коментарем «Fixed issue #1234. Removed duplicating data during an input geometry initialization» і такий самісінький коментар пишете на початку файлу програмного коду. У більшості компаній вже використовується Git, що може відображати коментарі, зміни та все інше, що стосується вашого коду. Тому не пишіть такі коментарі.

/*
* Copyright (c) Company 2022
*/

//10/7/2022 - John: Fixed issue #1234. Removed duplicating data during an input geometry initialization !!!USELESS

//STL
#include <iostream>

• Коментарі для інших учасників проєкту. Наприклад, Джон побачив у коді магічне число у функції, яку недавно написала Шелл, і додав коментар «Shelly, do not use the magic numbers.» Є безліч засобів для ручного код рев’ю, використовуйте їх для таких цілей. Або ж просто напишіть у месенджер, що і де потрібно підправити.

double circumference(double radius) {
    //Shelly, do not use the magic numbers. !!!USELESS
    return 2 * 3.14 * radius;
}

• Коментарі, що пояснюють імена функцій та змінних. Наприклад, змінна називається «mD». Тут краще дати таку назву змінної, що пояснюватиме її призначення, а не додавати коментар, який лише роздуває розмір програмного коду та кількість рядків, які потрібно скролити до потрібного місця.

class Foo {
    //Data of the Foo instance. !!!USELESS
    int mD = 10;
public:
    Foo() {}
};

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

int fibonacci(int n) {
    //This is dumb approach. The `Divide and Conquer` method is more efficient !!!USELESS
    if (n <= 1)
        return n;
    return fibonacci(n - 1) + fibonacci(n - 2);
}

Висновки

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

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

Підписуйтеся на Telegram-канал «DOU #tech», щоб не пропустити нові технічні статті