Урок №12. Коментарі

  Юрій  | 

  Оновл. 11 Кві 2020  | 

 220

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

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

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

Наприклад:

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

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

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

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

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

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

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

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

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

Наприклад:

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

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

Наприклад:

Або:

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

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

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

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

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

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

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

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

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

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

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

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

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

Або:

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

Підсумуємо:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1 Зірка2 Зірки3 Зірки4 Зірки5 Зірок (4 оцінок, середня: 5,00 з 5)
Loading...

Залишити відповідь

Ваш E-mail не буде опублікований. Обов'язкові поля відмічені *