Коментування коду: гарні, погані й огидні коментарі


Дізнайтесь більше про нові кар'єрні можливості в EchoUA. Цікаві проекти, ринкова оплата, гарний колектив. Надсилайте резюме та приєднуйтеся до нас.

“Гарний код – це самодокументований код”. Ви чули цю фразу раніше? Я також. Більше як за 20 років написання коду я чув цю фразу частіше від інших. Це вже кліше.

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

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

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

Документаційні коментарі

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

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

Подивіться на приклад коду з Lodash – популярної бібліотеки для JavaScript:

 /**
* Creates an object composed of keys generated from the results of running * each element of 'collection' thru 'iteratee'. The corresponding value of * each key is the number of times the key was returned by 'iteratee'. The * iteratee is invoked with one argument:  (value). * * @static * @memberOf_* @since 0.5.0 * @category Collection * @param {Array|Object} collection The collection to iterate over. * @param {Function} [iteratee=_.identity] The iteratee to transform keys. * @returns {Object} Returns the composed aggregate object. * @example * * _.countBy (1, Math.floor); * // => { '4': 1, '6': 2 } * * // The '_.property' iteratee shorthand.
* _.countBy (['one', 'two', 'three'], 'length'); * // => { '3': 2, '5': 1 } */ var countBy = createAggregator (function (result, value, key) { if (hasOwnProperty.call (result, key)) { ++result[key]; } else { baseAssignValue (result, key, 1); } });

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

Пояснювальні коментарі

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

Часто уточнювальний коментар до Вашого коду є його відображенням. За поясненням можна судити про те, навантажений Ваший код або ні. Слід намагатися видаляти пояснення в коді, спрощуючи його, адже “гарний код – самодокументованний код”.

Наведу приклад поганого, але забавного пояснення:

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

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

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

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

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

/*
Встановлює значення 32 для змінної age*/int age = 32;

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

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

function addSetEntry (set, value) { /* Не повертати 'set.add', тому що цей ланцюжок викликів не спрацює в IE 11. */ set.add (value); return set; }

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

Іноді тим самим “розумнішим” кодером можете виявитися Ви самі, тому в таких випадках краще залишати коментарі до коду, щоб в майбутньому заощадити свій і чужий час та нерви.

Коментар, наведений нижче, повністю відбиває викладену думку:

/**Шановний розробнику:
Щойно ти припиниш намагатися "оптимізувати" цей код, то зрозумієш, якої помилки ти припустився, взявшись за цю справу, будь ласка, збільш номер на лічильнику ниже для наступного розробника: кількість_годин_витрачено_дарма_тут = 42**/

Знову ж таки, коментар вище містить більше гумору, ніж користі. Вам СЛІД залишати коментарі, що застерігають інших від пошуку якогось “кращого рішення”, якщо Ви самі вже намагалися це зробити, але нічого гарного з цього не вийшло. У коментарі слід вказати, яке рішення Ви намагалися знайти і чому вирішили, що воно не підходить у цій ситуації або не працює.

/* не використовуйте глобальну функцію isFinite (), тому що вона повертає true для нульових значень*/Number.isFinite (value)

Огидні коментарі

Ми вже дізналися, що таке гарні й погані коментарі до коду. Тепер прийшов час ознайомитися з огидними коментарями.

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

При роботі з великими об’ємами коду Ви можете зіткнутися з різними негативними коментарями, починаючи від цинічних і депресивних до різко негативних і злих.

Відносно нешкідливий коментар:

/*Цей код - дно, я знаю. Можеш вивчати його далі й назвати мене недоумком.
*/

Відверто лютий коментар:

/* Клас, що використовується для обхідного рішення, - Richard being a f***ing idiot*/

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

Поважайте себе й інших розробників і не допускайте подібних коментарів у своєму коді!

  1. 1, 4.2, 6.3

Переклад статті “Putting comments in code: the good, the bad, and the ugly”.

Київ, Харків, Одеса, Дніпро, Запоріжжя, Кривий Ріг, Вінниця, Херсон, Черкаси, Житомир, Хмельницький, Чернівці, Рівне, Івано-Франківськ, Кременчук, Тернопіль, Луцьк, Ужгород, Кам'янець-Подільський, Стрий - за статистикою саме з цих міст програмісти найбільше переїжджають працювати до Львова. А Ви розглядаєте relocate?


Trends: https://yandex ru/clck/jsredir?from=yandex ru;search;web;;&text=&etext=1824 OtttcVUC5z5bcCOwD8_sJD2bNBoIe5IAs3rCx_kZ0qdsecttsLc-h7WxnTITcfrv ab2e611b4b959b839a93ba835edc9fbf503f6c18&uuid=&state=_BLhILn4SxNIvvL0W45KSic66uCIg23qh8iRG98qeIXme

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

Ваша e-mail адреса не оприлюднюватиметься. Обов’язкові поля позначені *