Внесення коментарів у код: добрі, погані та негарні.

Зупиніть мене, якщо ви чули це раніше ...

"Хороший код - це самодокументування".

За 20+ років написання коду на життя це одна фраза, яку я найбільше чув.

Це кліше.

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

Це правда? Так .

Це означає, що ви ніколи не повинні коментувати свій код? Ні .

У цій статті ми розглянемо хороші, погані та потворні, коли мова зайде про коментування вашого коду.

Для початку, насправді є два різні типи коментарів до коду. Я називаю їх коментарями до документації та роз'ясненнями .

Коментарі до документації

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

Чим далі видаляється із вихідного коду ваша документація щодо API, тим більша ймовірність, що вона з часом стане застарілою або неточною. Хороша стратегія пом'якшення цього полягає в тому, щоб вбудувати документацію безпосередньо в код, а потім використовувати інструмент для її вилучення.

Ось приклад коментаря до документації з популярної бібліотеки JavaScript під назвою Lodash.

Якщо порівняти ці коментарі з їхньою онлайн-документацією, ви побачите, що це точно відповідає.

Якщо ви пишете коментарі до документації, ви повинні переконатися, що вони відповідають узгодженим стандартам і що їх легко відрізнити від будь-яких вбудованих роз'яснень, які ви також можете додати. Деякі популярні та добре підтримувані стандарти та інструменти включають JSDoc для JavaScript, DocFx для dotNet та JavaDoc для Java.

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

Пояснення

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

Часто пояснення пояснення - це запах коду. Це говорить вам, що ваш код занадто складний. Вам слід прагнути видалити коментарі до роз'яснень та спростити код, тому що "хороший код самодокументується"

Ось приклад поганого - хоч і дуже розважального - пояснення.

/* * Replaces with spaces * the braces in cases * where braces in places * cause stasis.**/ $str = str_replace(array("\{","\}")," ",$str);

Замість того, щоб прикрашати трохи заплутане висловлювання розумною римою - у амфібраховому діметрі , не менше - автору було б набагато краще витратити час на функцію, яка полегшує читання та розуміння самого коду. Може функція з іменем, removeCurlyBracesвикликана з іншої функції з іменем sanitizeInput?

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

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

Також трапляються випадки, коли ви стикаєтесь із зайвим коментарем. Якщо код вже простий і очевидний, не потрібно додавати коментар.

Мовляв, не робіть цієї дурниці:

/*set the value of the age integer to 32*/int age = 32;

Тим не менше, бувають випадки, коли що б ви не робили з самим кодом, коментар до роз’яснень все одно є обов’язковим.

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

Ось хороший приклад від Lodash:

function addSetEntry(set, value) { /* Don't return `set.add` because it's not chainable in IE 11. */ set.add(value); return set; }

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

Іноді цей інший кодер - це ваше майбутнє.

У таких випадках найкраще заощадити всім час і збентеження та залишити коментар.

Наступний макет-коментар чудово фіксує цей сценарій:

/**Dear maintainer: Once you are done trying to 'optimize' this routine,and have realized what a terrible mistake that was,please increment the following counter as a warningto the next guy: total_hours_wasted_here = 42**/

Знову ж, вищесказане більше стосується того, щоб бути смішним, а не корисним. Але ТРЕБА залишити коментар, попереджаючи інших, щоб не застосовували якесь, здавалося б, очевидне «краще рішення», якщо ви вже спробували та відхилили його. І коли ви це зробите, у коментарі повинно бути вказано, яке рішення ви спробували і чому ви вирішили проти нього.

Ось простий приклад у JavaScript:

/* don't use the global isFinite() because it returns true for null values*/Number.isFinite(value)

Потворний

Отже, ми розглядали хороші і погані, а як щодо потворних?

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

Працюйте з достатньою кількістю кодів, і ви натрапите на коментарі, які варіюються від цинічних і гнітючих до темних і підлих.

Такі речі, як здавалося б, нешкідливі ...

/*This code sucks, you know it and I know it. Move on and call me an idiot later.*/

... до прямого середнього значення

/* Class used to workaround Richard being a f***ing idiot*/

These things may seem funny or may help release a bit of frustration in the moment, but when they make it into production code they end up making the coder who wrote them and their employer look unprofessional and bitter.

Don't do this.

If you enjoyed this article, please smash the applause icon a bunch of times to help spread the word. And if you want to read more stuff like this, please sign up for my weekly Dev Mastery newsletter below.