Коментарі в С++ / aCode

Коментар — це рядок (чи декілька рядків) тексту, який вставляється у вихідний код для пояснення того, що виконує цей код. В C++ є два типи коментарів: однорядкові та багаторядкові.

Зміст:

Однорядкові коментарі
Багаторядкові коментарі
Як правильно писати коментарі?
Закоментувати код

Однорядкові коментарі

Однорядкові коментарі — це коментарі, які пишуться після символів //. Вони розміщуються в окремих рядках і все, що знаходиться після цих символів коментування, — ігнорується компілятором. Наприклад:

std::cout << «Hello, world!» << std::endl; // все, що знаходиться від початку подвійного слешу, - ігнорується компілятором

1	std::cout << «Hello, world!» << std::endl; // все, що знаходиться від початку подвійного слешу, - ігнорується компілятором

Як правило, однорядкові коментарі використовуються для пояснення одного рядка коду:

std::cout << «Hello, world!» << std::endl; // cout і endl знаходяться в бібліотеці iostream
std::cout << «It is so exciting!» << std::endl; // ці коментарі ускладнюють читання коду
std::cout << «Yeah!» << std::endl; // особливо, коли рядки різної довжини

std::cout << «Hello, world!» << std::endl; // cout і endl знаходяться в бібліотеці iostream

std::cout << «It is so exciting!» << std::endl; // ці коментарі ускладнюють читання коду

std::cout << «Yeah!» << std::endl; // особливо, коли рядки різної довжини

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

// cout і endl знаходяться в бібліотеці iostream
std::cout << «Hello, world!» << std::endl;

// Тепер вже читати стало легше
std::cout << «It is so exciting!» << std::endl;

// Чи не так?
std::cout << «Yeah!» << std::endl;

// cout і endl знаходяться в бібліотеці iostream

std::cout << «Hello, world!» << std::endl;

// Тепер вже читати стало легше

std::cout << «It is so exciting!» << std::endl;

// Чи не так?

std::cout << «Yeah!» << std::endl;

Багаторядкові коментарі

Багаторядкові коментарі — це коментарі, які пишуться між символами /* */. Все, що знаходиться між зірочками, — ігнорується компілятором:

/* Це багаторядковий коментар.
Цей рядок ігнорується
і цей також. */

/* Це багаторядковий коментар.

Цей рядок ігнорується

і цей також. */

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

/* Це багаторядковий коментар.
* Зірочки зліва
* спрощують читання тексту
*/

/* Це багаторядковий коментар.

* Зірочки зліва

* спрощують читання тексту

Багаторядкові коментарі не можуть бути вкладеними (знаходитися всередині інших коментарів):

/* Це багаторядковий /* коментар */ а це вже не коментар */
// Верхній коментар закінчується перед першою */, а не перед другою */

1 2	/* Це багаторядковий /* коментар / а це вже не коментар / // Верхній коментар закінчується перед першою /, а не перед другою /

Правило: Ніколи не пишіть вкладені коментарі.

Як правильно писати коментарі?

По-перше, на рівні бібліотек/програм/функцій коментарі відповідають на питання “Що?”: “Що роблять ці бібліотеки/програми/функції?”. Наприклад:

// Ця програма обчислює оцінку студента за навчальний семестр на основі його оцінок за модулі

// Ця функція використовує метод Ньютона для обчислення кореня функції
 
// Наступний код генерує випадкове число

// Ця програма обчислює оцінку студента за навчальний семестр на основі його оцінок за модулі

// Ця функція використовує метод Ньютона для обчислення кореня функції

// Наступний код генерує випадкове число

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

По-друге, всередині бібліотек/програм/функцій коментарі відповідають на питання “Як?”: “Як код виконує завдання?”. Наприклад:

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

/* Для обчислення підсумкової оцінки студента, ми додаємо всі його оцінки за уроки і домашні завдання,

а потім ділимо число, яке отримали, на загальну кількість оцінок.

Таким чином, ми отримуємо середній бал студента. */

Або:

// Щоб отримати рандомний (випадковий) елемент, ми виконуємо наступне:

// 1) Складаємо список всіх елементів.
// 2) Обчислюємо середнє значення для кожного елемента на основі його ваги, кольору і ціни.
// 3) Вибираємо будь-яке число.
// 4) Визначаємо відповідність елемента випадково обраному числу.
// 5) Повертаємо випадковий елемент.

// Щоб отримати рандомний (випадковий) елемент, ми виконуємо наступне:

// 1) Складаємо список всіх елементів.

// 2) Обчислюємо середнє значення для кожного елемента на основі його ваги, кольору і ціни.

// 3) Вибираємо будь-яке число.

// 4) Визначаємо відповідність елемента випадково обраному числу.

// 5) Повертаємо випадковий елемент.

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

По-третє, на рівні стейтментів (однорядкового коду) коментарі відповідають на питання “Чому?”: “Чому код виконує завдання саме так, а не інакше?”. Поганий коментар на рівні стейтментів пояснює, що виконує код. Якщо ви коли-небудь писали код, який був настільки складним, що потрібен був коментар, який би пояснював, що він виконує, то вам потрібно було не писати коментар, а переписувати код.

Приклади поганих і хороших однорядкових коментарів:

Поганий коментар:

// Присвоюємо змінній sight значення 0
sight = 0;

1 2	// Присвоюємо змінній sight значення 0 sight = 0;

(По коду це і так зрозуміло)

Хороший коментар:

// Гравець випив зілля сліпоти і нічого не бачить
sight = 0;

1 2	// Гравець випив зілля сліпоти і нічого не бачить sight = 0;

(Тепер ми знаємо, ЧОМУ зір у гравця дорівнює нулю)

Поганий коментар:

// Обчислюємо вартість елементів
cost = items / 2 * storePrice;

1 2	// Обчислюємо вартість елементів cost = items / 2 * storePrice;

(Так, ми бачимо, що тут відбувається обчислення вартості, але чому елементи діляться на 2?)

Хороший коментар:

// Нам потрібно розділити всі елементи на 2, тому що вони куплені парами
cost = items / 2 * storePrice;

1 2	// Нам потрібно розділити всі елементи на 2, тому що вони куплені парами cost = items / 2 * storePrice;

(Ось тепер зрозуміло!)

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

Хороші коментарі:

// Ми вирішили використовувати список замість масиву,
// тому що масиви здійснюють повільну вставку.

1 2	// Ми вирішили використовувати список замість масиву, // тому що масиви здійснюють повільну вставку.

або

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

1 2	// Ми використовуємо метод Ньютона для обчислення кореня функції, // оскільки іншого детермінованого способу вирішення цього завдання немає.

І, нарешті, коментарі потрібно писати так, щоб людина, яка не має ані найменшого уявлення про те, що робить ваш код, — змогла в ньому розібратися. Дуже часто трапляються ситуації, коли програміст каже: «Це ж абсолютно очевидно, що робить цей код! Я це точно не забуду!”. Вгадайте, що трапиться через декілька тижнів або навіть днів? Це не зовсім очевидно, і ви здивуєтеся, як швидко ви забудете, що робить ваш код. Ви (або хтось інший) будете дуже вдячні собі за те, що залишили коментарі, пояснюючи на людській мові що, як і чому виконує ваш код. Читати окремі рядки коду — легко, а от розуміти їх логіку і сенс — складно.

Підсумовуємо:

На рівні бібліотек/програм/функцій залишайте коментарі, відповідаючи на питання “Що?”.

Всередині бібліотек/програм/функцій залишайте коментарі, відповідаючи на питання “Як?”.

На рівні стейтментів залишайте коментарі, відповідаючи на питання “Чому?”.

Закоментувати код

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

Щоб закоментувати один рядок коду, використовуйте однорядкові символи коментування //.

Не закоментовано:

std::cout << 1;

1	std::cout << 1;

Закоментовано:

//    std::cout << 1;

1	// std::cout << 1;

Щоб закоментувати блок коду, використовуйте багаторядкові символи коментування // на кожному рядку, або символи багаторядкового коментаря /* */.

Не закоментовано:

std::cout << 1;
std::cout << 2;
std::cout << 3;

std::cout << 1;

std::cout << 2;

std::cout << 3;

Закоментовано символами однорядкового коментаря:

//    std::cout << 1;
//    std::cout << 2;
//    std::cout << 3;

// std::cout << 1;

// std::cout << 2;

// std::cout << 3;

Закоментовано символами багаторядкового коментаря:

/*
     std::cout << 1;
     std::cout << 2;
     std::cout << 3;
*/

std::cout << 1;

std::cout << 2;

std::cout << 3;

Є декілька причин, чому потрібно в певних ситуаціях закоментовувати код:

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

Причина №2: Ви написали код, який компілюється, але працює не так як потрібно і зараз у вас немає часу з цим розбиратися. Закоментуйте код, а потім, коли буде час, виправте в ньому помилки.

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

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

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

Оцінити статтю: