Įrašyti komentarus kodais: geri, blogi ir negražūs.

Sustabdyk mane, jei jau girdėjai šį ...

„Geras kodas yra savęs dokumentavimas“.

Per daugiau nei 20 metų rašant kodą pragyvenimui, tai yra viena frazė, kurią girdėjau labiausiai.

Tai klišė.

Kaip ir daugelis klišių, ji turi tiesos branduolį. Tačiau šia tiesa buvo taip piktnaudžiaujama, kad dauguma žmonių, ištarę frazę, neįsivaizduoja, ką ji iš tikrųjų reiškia.

Ar tai tiesa? Taip .

Ar tai reiškia, kad niekada neturėtumėte komentuoti savo kodo? Ne .

Šiame straipsnyje mes apžvelgsime gerus, blogus ir negražius komentuodami savo kodą.

Pradedantiesiems yra tikrai du skirtingi kodo komentarų tipai. Aš juos vadinu dokumentų komentarais ir paaiškinimais .

Dokumentacijos komentarai

Dokumentacijos komentarai skirti tiems, kurie greičiausiai suvartos jūsų šaltinio kodą, bet greičiausiai jo neskaitys. Jei kuriate biblioteką ar sistemą, kurią naudos kiti kūrėjai, jums reikia tam tikros formos API dokumentų.

Kuo toliau jūsų API dokumentacija bus pašalinta iš šaltinio kodo, tuo didesnė tikimybė, kad laikui bėgant ji bus pasenusi ar netiksli. Gera strategija tai sušvelninti yra dokumentų įterpimas tiesiai į kodą, o tada naudojimas įrankiu juos išgauti.

Pateikiame populiarios „JavaScript“ bibliotekos „Lodash“ dokumentacijos komentaro pavyzdį.

Jei palyginsite šiuos komentarus su jų internetine dokumentacija, pamatysite, kad tai tiksli atitiktis.

Jei rašote dokumentacijos komentarus, turėtumėte įsitikinti, kad jie atitinka nuoseklų standartą ir kad juos galima lengvai atskirti nuo bet kokių aiškių komentarų, kuriuos taip pat galite pridėti. Kai kurie populiarūs ir gerai palaikomi standartai ir įrankiai yra „JSDoc“, skirtas „JavaScript“, „DocFx“, skirtas „dotNet“, ir „JavaDoc“, skirtas „Java“.

Šių komentarų trūkumas yra tas, kad jie gali padaryti jūsų kodą labai „triukšmingą“ ir sunkiau skaitomą visiems, kurie aktyviai dalyvauja jo priežiūroje. Geros naujienos yra tai, kad dauguma kodo redaktorių palaiko „kodo lankstymą“, kuris leidžia sutraukti komentarus, kad galėtume sutelkti dėmesį į kodą.

Paaiškinimo komentarai

Paaiškinimo komentarai skirti visiems (įskaitant būsimą save), kuriam gali tekti prižiūrėti, pertvarkyti ar išplėsti jūsų kodą.

Dažnai paaiškinimo komentaras yra kodo kvapas. Jame sakoma, kad jūsų kodas yra per sudėtingas. Turėtumėte stengtis pašalinti paaiškinimo komentarus ir supaprastinti kodą, nes „geras kodas yra savęs dokumentavimas“.

Štai blogo, nors ir labai linksmo, paaiškinimo komentaro pavyzdys.

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

Užuot papuošęs šiek tiek painų teiginį protingu rimu - ne mažiau nei amfibracho dimetru , autoriui būtų buvę kur kas geriau praleisti laiką funkcijai, kuri palengvina patį kodą lengviau suprasti ir suprasti. Gal funkcija pavadinta, removeCurlyBracesiškviesta iš kitos pavadintos funkcijos sanitizeInput?

Nesupraskite manęs neteisingai, yra atvejų, ypač kai slogiate per triuškinantį krūvį, kai šiek tiek humoro įpurškimas gali būti naudingas sielai. Bet kai rašote juokingą komentarą, kad kompensuotumėte blogą kodą, žmonės iš tikrųjų rečiau refraktuoja ir pataiso kodą vėliau.

Ar tikrai norite būti atsakingas už tai, kad apiplėšėte visus būsimus programuotojus džiaugsmo skaityti tą protingą mažą rimą? Dauguma koduotojų sukikeno ir judėjo toliau, nepaisydami kodo kvapo.

Kartais pasitaiko ir komentaro, kuris yra nereikalingas. Jei kodas jau paprastas ir akivaizdus, ​​komentaro pridėti nereikia.

Panašu, nedaryk šios nesąmonės:

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

Vis dėlto yra atvejų, kai nesvarbu, ką darote su pačiu kodu, paaiškinimo komentaras vis tiek yra pagrįstas.

Paprastai tai atsitinka, kai jums reikia pridėti kontekstą prie ne intuityvaus sprendimo.

Štai geras pavyzdys iš „Lodash“:

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

Taip pat yra atvejų, kai - daug pagalvojus ir eksperimentavus - paaiškėja, kad iš pažiūros naivus problemos sprendimas iš tikrųjų yra geriausias. Tokiais atvejais beveik neišvengiama, kad koks nors kitas programuotojas sugalvos, kad yra daug protingesnis nei jūs, ir pradės blaškytis su kodu, kad sužinotų, jog jūsų kelias visą laiką buvo geriausias.

Kartais tas kitas programuotojas yra tavo būsimasis aš.

Tokiais atvejais geriausia sutaupyti laiko ir gėdos bei palikti komentarą.

Šis pavyzdinis komentaras puikiai užfiksuoja šį scenarijų:

/**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**/

Again, the above is more about being funny than being helpful. But you SHOULD leave a comment warning others not to pursue some seemingly obvious “better solution,” if you’ve already tried and rejected it. And when you do, the comment should specify what solution you tried and why you decided against it.

Here’s a simple example in JavaScript:

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

The Ugly

So, we’ve looked at the good and the bad, but what about the ugly?

Unfortunately, there are times in any job where you’ll find yourself frustrated and when you write code for a living, it can be tempting to vent that frustration in code comments.

Work with enough code bases and you’ll come across comments that range from cynical and depressing to dark and mean spirited.

Things like the seemingly harmless…

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

…to the downright mean

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

Šie dalykai gali atrodyti juokingi arba gali padėti atleisti šiek tiek nusivylimo šiuo metu, tačiau kai jie sukuria gamybos kodą, jie juos parašiusį koduotoją ir jų darbdavį priverčia atrodyti neprofesionaliai ir karti.

Nedaryk to.

Jei jums patiko šis straipsnis, kelis kartus sutriuškinkite plojimų piktogramą, kad padėtumėte skleisti žinią. Ir jei norite perskaityti daugiau panašių dalykų, užsiregistruokite žemiau esančiame savaitiniame „Dev Mastery“ naujienlaiškyje.