Коментар — це рядок (чи декілька рядків) тексту, який вставляється у вихідний код для пояснення того, що виконує цей код. В C++ є два типи коментарів: однорядкові та багаторядкові.
Однорядкові коментарі
Однорядкові коментарі — це коментарі, які пишуться після символів //
. Вони розміщуються в окремих рядках і все, що знаходиться після цих символів коментування, — ігнорується компілятором. Наприклад:
1 |
std::cout << «Hello, world!» << std::endl; // все, що знаходиться від початку подвійного слешу, - ігнорується компілятором |
Як правило, однорядкові коментарі використовуються для пояснення одного рядка коду:
1 2 3 |
std::cout << «Hello, world!» << std::endl; // cout і endl знаходяться в бібліотеці iostream std::cout << «It is so exciting!» << std::endl; // ці коментарі ускладнюють читання коду std::cout << «Yeah!» << std::endl; // особливо, коли рядки різної довжини |
Розміщуючи коментарі праворуч від коду, ми ускладнюємо собі як читання коду, так і читання коментарів. Тому однорядкові коментарі краще розміщувати над рядками коду:
1 2 3 4 5 6 7 8 |
// cout і endl знаходяться в бібліотеці iostream std::cout << «Hello, world!» << std::endl; // Тепер вже читати стало легше std::cout << «It is so exciting!» << std::endl; // Чи не так? std::cout << «Yeah!» << std::endl; |
Багаторядкові коментарі
Багаторядкові коментарі — це коментарі, які пишуться між символами /* */
. Все, що знаходиться між зірочками, — ігнорується компілятором:
1 2 3 |
/* Це багаторядковий коментар. Цей рядок ігнорується і цей також. */ |
Оскільки все, що знаходиться між зірочками, — ігнорується, то інколи ви можете побачити наступне:
1 2 3 4 |
/* Це багаторядковий коментар. * Зірочки зліва * спрощують читання тексту */ |
Багаторядкові коментарі не можуть бути вкладеними (знаходитися всередині інших коментарів):
1 2 |
/* Це багаторядковий /* коментар */ а це вже не коментар */ // Верхній коментар закінчується перед першою */, а не перед другою */ |
Правило: Ніколи не пишіть вкладені коментарі.
Як правильно писати коментарі?
По-перше, на рівні бібліотек/програм/функцій коментарі відповідають на питання “Що?”: “Що роблять ці бібліотеки/програми/функції?”. Наприклад:
1 2 3 4 5 |
// Ця програма обчислює оцінку студента за навчальний семестр на основі його оцінок за модулі // Ця функція використовує метод Ньютона для обчислення кореня функції // Наступний код генерує випадкове число |
Всі ці коментарі дозволяють зрозуміти, що робить програма, без необхідності переглядати вихідний (первинний) код. Це особливо важливо фахівцям, які працюють в команді, де не кожний колега знайомий з усім наявним кодом.
По-друге, всередині бібліотек/програм/функцій коментарі відповідають на питання “Як?”: “Як код виконує завдання?”. Наприклад:
1 2 3 |
/* Для обчислення підсумкової оцінки студента, ми додаємо всі його оцінки за уроки і домашні завдання, а потім ділимо число, яке отримали, на загальну кількість оцінок. Таким чином, ми отримуємо середній бал студента. */ |
Або:
1 2 3 4 5 6 7 |
// Щоб отримати рандомний (випадковий) елемент, ми виконуємо наступне: // 1) Складаємо список всіх елементів. // 2) Обчислюємо середнє значення для кожного елемента на основі його ваги, кольору і ціни. // 3) Вибираємо будь-яке число. // 4) Визначаємо відповідність елемента випадково обраному числу. // 5) Повертаємо випадковий елемент. |
Ці коментарі дозволяють користувачеві зрозуміти, яким чином код виконує поставлене йому завдання.
По-третє, на рівні стейтментів (однорядкового коду) коментарі відповідають на питання “Чому?”: “Чому код виконує завдання саме так, а не інакше?”. Поганий коментар на рівні стейтментів пояснює, що виконує код. Якщо ви коли-небудь писали код, який був настільки складним, що потрібен був коментар, який би пояснював, що він виконує, то вам потрібно було не писати коментар, а переписувати код.
Приклади поганих і хороших однорядкових коментарів:
Поганий коментар:
1 2 |
// Присвоюємо змінній sight значення 0 sight = 0; |
(По коду це і так зрозуміло)
Хороший коментар:
1 2 |
// Гравець випив зілля сліпоти і нічого не бачить sight = 0; |
(Тепер ми знаємо, ЧОМУ зір у гравця дорівнює нулю)
Поганий коментар:
1 2 |
// Обчислюємо вартість елементів cost = items / 2 * storePrice; |
(Так, ми бачимо, що тут відбувається обчислення вартості, але чому елементи діляться на 2?)
Хороший коментар:
1 2 |
// Нам потрібно розділити всі елементи на 2, тому що вони куплені парами cost = items / 2 * storePrice; |
(Ось тепер зрозуміло!)
Програмістам часто доводиться приймати важкі рішення з приводу того, яким саме способом вирішити проблему. А коментарі існують для того, щоб нагадати собі (або пояснити іншим) причину, чому ви написали код саме так, а не інакше.
Хороші коментарі:
1 2 |
// Ми вирішили використовувати список замість масиву, // тому що масиви здійснюють повільну вставку. |
або
1 2 |
// Ми використовуємо метод Ньютона для обчислення кореня функції, // оскільки іншого детермінованого способу вирішення цього завдання немає. |
І, нарешті, коментарі потрібно писати так, щоб людина, яка не має ані найменшого уявлення про те, що робить ваш код, — змогла в ньому розібратися. Дуже часто трапляються ситуації, коли програміст каже: «Це ж абсолютно очевидно, що робить цей код! Я це точно не забуду!”. Вгадайте, що трапиться через декілька тижнів або навіть днів? Це не зовсім очевидно, і ви здивуєтеся, як швидко ви забудете, що робить ваш код. Ви (або хтось інший) будете дуже вдячні собі за те, що залишили коментарі, пояснюючи на людській мові що, як і чому виконує ваш код. Читати окремі рядки коду — легко, а от розуміти їх логіку і сенс — складно.
Підсумовуємо:
На рівні бібліотек/програм/функцій залишайте коментарі, відповідаючи на питання “Що?”.
Всередині бібліотек/програм/функцій залишайте коментарі, відповідаючи на питання “Як?”.
На рівні стейтментів залишайте коментарі, відповідаючи на питання “Чому?”.
Закоментувати код
Закоментувати код означає помістити в коментарі один або декілька рядків коду. Таким чином, ви зможете (тимчасово) відокремити певну частину коду від компіляції.
Щоб закоментувати один рядок коду, використовуйте однорядкові символи коментування //
.
Не закоментовано:
1 |
std::cout << 1; |
Закоментовано:
1 |
// std::cout << 1; |
Щоб закоментувати блок коду, використовуйте багаторядкові символи коментування //
на кожному рядку, або символи багаторядкового коментаря /* */
.
Не закоментовано:
1 2 3 |
std::cout << 1; std::cout << 2; std::cout << 3; |
Закоментовано символами однорядкового коментаря:
1 2 3 |
// std::cout << 1; // std::cout << 2; // std::cout << 3; |
Закоментовано символами багаторядкового коментаря:
1 2 3 4 5 |
/* std::cout << 1; std::cout << 2; std::cout << 3; */ |
Є декілька причин, чому потрібно в певних ситуаціях закоментовувати код:
Причина №1: Ви працюєте над новою частиною коду, яка поки що не є робочою, але вам потрібно запустити програму. Компілятор не дозволить вам виконати програму, якщо в ній присутні помилки. Тимчасове відокремлення коментуванням неробочого коду від робочого дозволить вам запустити програму. Коли код буде робочий, то ви зможете його легко розкоментувати і продовжити роботу.
Причина №2: Ви написали код, який компілюється, але працює не так як потрібно і зараз у вас немає часу з цим розбиратися. Закоментуйте код, а потім, коли буде час, виправте в ньому помилки.
Причина №3: Пошук кореня помилки. Якщо програма генерує не ті результати (або взагалі відбувається збій), які вам потрібно, — корисно буде по черзі “вимикати” частини вашого коду, щоб зрозуміти які з них робочі, а які — створюють проблеми. Якщо ви закоментуєте один або декілька рядків коду і програма почне коректно працювати (чи зникнуть збої), то шанси того, що останнє, що ви закоментували, є помилкою — дуже великі. Після цього ви зможете розібратися з тим, чому ж цей код працює не так, як потрібно.
Причина №4: Тестування нового коду. Замість видалення старого коду, ви можете його закоментувати і залишити для довідки, поки не будете впевнені, що ваш новий код працює так, як потрібно. Як тільки ви будете впевнені в новому коді, то зможете без проблем видалити старі фрагменти коду. Якщо ж новий код у вас працюватиме не так, як потрібно, то ви зможете його видалити і відновити старий код.
Примітка: У всіх наступних уроках я буду використовувати коментарі в ілюстративних цілях. Уважні читачі зможуть помітити, що за вищевказаними стандартами більшість з цих коментарів будуть поганими. Але пам’ятайте, що використовувати я їх буду в освітніх цілях, а не для демонстрації хороших прикладів.