Коментування C та C++ коду
Програми мають бути красивими та зрозумілими. Якщо хтось каже вам протилежне, намагайтеся не слухати його поради. Хороша програма гарна, як у своїй концепції — алгоритм, що використовується. Хороший код не рясніє тернарними операторами та арифметикою покажчиків, і, принаймні, не повинен бути оптимізованим, щоб заощадити кілька секунд операції, яка виконується раз на кілька місяців. Але код, навіть найідеальніший, часто вимагає деякої допомоги від російської, англійської (або іншої) мов. Іноді алгоритм занадто складний для швидкого або повного розуміння без будь-яких пояснень, або в коді використовується якась езотерична функція із загадковим іменем, що вводить в оману. І якщо ви збираєтеся писати довгоживучу програму, швидше за все через кілька років вам доведеться поміняти якусь частину коду, яку ви не захотіли прокоментувати - або це доведеться зробити комусь іншому, він прокляне вас. Нарешті, коментування коду також сприяє глибокому розумінню програми і допоможе виявити помилки до початку тестування. З естетичних і практичних міркувань хороше коментування є важливим навичкою програмування, що часто не береться до уваги.
Перш ніж говорити про те, як коментувати, попереджаю: не піддавайтеся спокусі і не коментуйте занадто багато. Як добре писати, так само добре і кодувати. Ви ж не хочете включати коментар, який говорить читачеві щось само собою зрозуміле, або щось, що можна виділити з одного рядка коду.(Ви ж не пишете код щоб навчити когось програмування!) Наприклад, int callCount = 0; //Визначення цілісної змінної , несе ніякої значної інформації. Коментарі мають виявляти основні структури коду, а чи не поверхневі деталі. Більш значущим коментар буде int callCount = 0; //кількість звернень до функції.
Коментарі не повинні бути надто довгими. Коментарі не повинні містити деталі для деталей. Тільки якщо якийсь факт необхідний чи цікавий, він повинен бути донесений до читача програми. Якщо ви читали чужі програми, вам не захотілося б переглядати текст з описом тонкощів для роботи циклу тільки для того, щоб зрозуміти, що ви могли б виявити цю ж інформацію, просто прочитавши цикл.
Для майбутніх читачів зазвичай слід включати деякі заголовки у верхню частину вашої програми. Ця інформація може включати ваше ім'я та контактну інформацію, дату останньої зміни коду, мету програми та, при необхідності, короткий виклад алгоритму або проектні рішення. Ви також можете включити список відомих помилок, недоліків або пропозицій щодо покращення. Це зручно для демаркації цієї частини файлу програми у великий блок коментарів.
Цю форму коментаря найкраще робити в кінці програми, за винятком, мабуть, огляду алгоритму, який може допомогти висловити ваші думки, коли ви маєте справу з новими, заплутаними чи складними поняттями.
По-друге, при створенні нового класу або нового визначення функції, ви повинні додати коментар, який пояснює клас або функцію.Що стосується класу, вам слід пояснити його мету, доступні функції та змінні, будь-які обмеження класу, а також інформацію, яка може знадобитися програмісту, якщо він чи вона захоче успадкуватись від класу. При визначенні функції ви повинні описати, що робить ця функція і чи має побічні ефекти, такі як зміна глобальних змінних, що взаємодіють з користувачем, і так далі. Це також зручно для опису аргументів, які приймає функція, та значень, якщо такі є, які вона повертає: наприклад, якщо у вас є функція findTime(int distance, int speed) , ви хотіли б повідомити користувача, що відстань вимірюється в сажнях, швидкість - в аршинах за три дні, і що функція повертає час подорожі в епохах.
Ви могли б зробити імена змінних більш описовими, але необхідно збільшити інформативність всередині функції, тому що відносини між відстанню і швидкістю - істотна особливість, а не відносини між відстаннюінородів і speedinfurlongsperfortnight . Як ви бачите, довгі імена занадто складні і ускладнюють пошук помилок. Загалом імена змінних мають бути описовими настільки, щоб висловити відносини між змінними. Усі деталі реалізації слід відобразити у коментарях у відповідних місцях. Наприклад, у наведеній вище функції, функція, що викликає, повинна знати одиниці, але ці одиниці не мають значення всередині функції (крім випадків, коли робляться перетворення, але програміст повинен зробити запис про це в момент перетворення). Щоб уникнути плутанини, слід уникати скорочень; слова можуть бути скорочені кількома способами, і одна абревіатура може означати різні слова.Немає скорочень – немає проблем.
По-третє, при додаванні коментарів у коді, будьте стриманими. Чим менше ви скажете, тим краще, якщо ви спробуєте бути точним, ви зробите коментарі більш корисними, і синтезуватимете потік вашої програми, а не повторювати те, що код вже говорить користувачеві. Код повинен відповідати алгоритму, а не ходити довкола та навколо.
По-четверте, добрі коментарі можуть покращити ваше програмування. Ви можете використовувати коментарі для організації коду, вставляючи їх перед блоком коду, а не всередині його, наприклад, коли у вас є довгий блок умовних операторів, ви можете прокоментувати те, що має відбутися при виконанні різних умов перед самим кодом. Вчиняючи таким чином, ви позбавите себе тягаря запам'ятовування подробиць всієї програми, що дозволить зосередитися на реалізації одного з аспектів.
Крім того, коли ви коментуєте в процесі програмування, ви не напишіть код, який ви сподіваєтеся, буде працювати, якщо ви поясните, чому він працює. (Майте на увазі, що якщо код настільки складний, що ви не знаєте, як він працює, то вам, ймовірно, слід прокоментувати його для себе та інших.)
Нарешті, майте на увазі, що те, що здається очевидним сьогодні, може здатися зовсім навіть не очевидним пізніше. Хоча вам не слід коментувати надто багато, обов'язково прокоментуйте нестандартні алгоритми. Вам не потрібно коментувати ідіоми програмування, але прокоментуйте нестандартний алгоритм для вашої програми, яким би простим він вам не здавався.Без сумніву, він здаватиметься незнайомим через три тижні після написання коду, і якщо ви плануєте (і навіть якщо не плануєте) повернутися до коду, це буде незмірно корисно.
Коментарі для себе та інших.
Можливо вам доведеться працювати з не коментованим кодом, і буде корисно коментувати цей код у міру того, як ви з ним знаєте. Це може бути також просто, як зміна імен змінних, скажімо, r , x , і y на currentNumber , largestPrime і currentDivisor . Якщо пощастить, зробивши це кілька разів, ви зрозумієте мудрість коментування коду. Крім того, ви побачите велику елегантність добре прокоментованого, ретельно написаного шматка коду в порівнянні з якось написаним, аби «працював».
C++: Коментарі в С++
Крім коду, у файлах з вихідним кодом можуть бути коментарі. Це текст, який не є частиною програми та потрібен програмістам для позначок. З їхньою допомогою додають пояснення, як працює код, які тут помилки потрібно виправити чи не забути щось додати пізніше.
Коментарі в С++ бувають двох видів:
Однорядкові коментарі
Однорядкові коментарі починаються з //. Після цих двох символів може слідувати будь-який текст, весь рядок не буде аналізуватись і виконуватись.
Коментар може займати весь рядок. Якщо одного рядка мало, то створюються кілька коментарів:
// For Winterfell! // For Lanisters!
Коментар може перебувати на рядку після якогось коду:
int index <0>; // counter initialization
Багаторядкові коментарі
Багаторядкові коментарі починаються з /* і закінчуються */ .
/* Це програмне забезпечення для message to console */ int main()
Такі коментарі зазвичай використовують для документування коду, наприклад, функцій.
Завдання
Виведіть у консоль рядок Hello Jon Snow!
У будь-якому місці програми створіть однорядковий коментар із текстом: You know nothing, Jon Snow! .
Не забудьте додати переклад рядка за допомогою функції std::endl або символу \n
Якщо ви зайшли в глухий кут, то саме час поставити питання в «Обговореннях». Як правильно поставити запитання:
- Обов'язково докладіть виведення тестів, без нього практично неможливо зрозуміти, що не так, навіть якщо ви покажете свій код. Програмісти погано виконують код у голові, але за помилкою майже завжди зрозуміло, куди дивитися.
Тести влаштовані таким чином, що вони перевіряють рішення різними способами та на різних даних. Часто рішення працює з одними вхідними даними, але з іншими. Щоб розібратися з цим моментом, вивчіть вкладку «Тести» та уважно подивіться на виведення помилок, у якому є підказки.
Це нормально 🙆, у програмуванні одне завдання можна виконати безліччю способів. Якщо ваш код пройшов перевірку, він відповідає умовам завдання.
У поодиноких випадках буває, що рішення підігнано під тести, але це видно відразу.
Створювати навчальні матеріали, зрозумілі всім без винятку, досить складно. Ми дуже намагаємося, але завжди є що покращувати. Якщо ви зустріли матеріал, який вам незрозумілий, напишіть проблему в «Обговореннях». Ідеально, якщо ви сформулюєте незрозумілі моменти як запитань. Зазвичай нам потрібно кілька днів для внесення поправок.
До речі, ви також можете брати участь у покращенні курсів: унизу є посилання на вихідний код уроків, який можна правити прямо з браузера.
