Поставяне на коментари в код: добрите, лошите и грозните.

Спрете ме, ако сте чували това преди ...

„Добрият код се самодокументира.“

След над 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.