Kommentaaride sisestamine koodidesse: head, halvad ja koledad.

Peatage mind, kui olete seda varem kuulnud ...

"Hea kood on ise dokumenteerimine."

Enam kui 20 aasta jooksul elatise jaoks koodi kirjutamise ajal olen seda fraasi kuulnud kõige rohkem.

See on klišee.

Ja nagu paljudel klišeedel, on ka sellel tõetera. Kuid seda tõde on nii kuritarvitatud, et enamikul fraasi lausuvatel inimestel pole aimugi, mida see tegelikult tähendab.

Kas see on tõsi? Jah .

Kas see tähendab, et te ei tohiks kunagi oma koodi kommenteerida? Ei .

Selles artiklis vaatleme teie koodi kommenteerimisel häid, halbu ja inetuid.

Alustuseks on tõesti kahte erinevat tüüpi koodikommentaare. Nimetan neid dokumentatsioonikommentaarideks ja selgituskommentaarideks .

Dokumentatsiooni kommentaarid

Dokumentatsiooni kommentaarid on mõeldud kõigile, kes tõenäoliselt teie lähtekoodi tarbivad, kuid tõenäoliselt seda läbi ei loe. Kui loote teeki või raamistikku, mida teised arendajad kasutavad, vajate mingis vormis API dokumentatsiooni.

Mida kaugem on teie API dokumentatsioon lähtekoodist eemaldatud, seda suurem on tõenäosus, et see aja jooksul vananeb või on ebatäpne. Hea strateegia selle leevendamiseks on dokumentide otse koodi sisestamine ja seejärel selle väljavõtmiseks tööriista kasutamine.

Siin on näide dokumentatsiooni kommentaarist populaarsest JavaScripti teegist nimega Lodash.

Kui võrdlete neid kommentaare nende veebidokumentatsiooniga, näete, et need vastavad täpselt.

Kui kirjutate dokumentatsioonikommentaare, peaksite tagama, et need järgiksid järjepidevat standardit ja oleksid hõlpsasti eristatavad kõigist siseselgitavatest kommentaaridest, mida võiksite ka lisada. Mõned populaarsed ja hästi toetatud standardid ja tööriistad hõlmavad JSDoci JavaScripti jaoks, DocFxi dotNeti jaoks ja JavaDoci Java jaoks.

Selliste kommentaaride negatiivne külg on see, et need võivad muuta teie koodi väga "lärmakaks" ja raskemini loetavaks kõigile, kes on selle hooldamisega aktiivselt seotud. Hea uudis on see, et enamik koodiredaktoreid toetab koodide voltimist, mis võimaldab meil kommentaarid kokku ahendada, et saaksime koodile keskenduda.

Selgitavad märkused

Selgituskommentaarid on mõeldud kõigile (sh teie tulevasele minale), kellel võib tekkida vajadus teie koodi hooldada, refrakteerida või laiendada.

Sageli on selgituskomment koodilõhn. See ütleb teile, et teie kood on liiga keeruline. Peaksite püüdma selgituskommentaarid eemaldada ja selle asemel koodi lihtsustada, sest „hea kood on ise dokumenteeriv”.

Siin on näide halvast - kuigi väga meelelahutuslikust - selgituskommentaarist.

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

Selle asemel, et kaunistada veidi segane avaldus nutika riimiga - mitte vähem amfibrachi dimeetris -, oleks autoril olnud palju parem kulutada aega funktsioonile, mis muudab koodi ise hõlpsamini loetavaks ja arusaadavaks. Võib-olla funktsioon nimega, removeCurlyBraceskutsutud teiselt nimega funktsioonilt sanitizeInput?

Ärge saage valesti aru, on juhtumeid - eriti siis, kui teete tohutut koormust -, kus natuke huumorit süstida võib hingele kasulik olla. Kuid kui kirjutate naljaka kommentaari halva koodi korvamiseks, muudab see inimesi tõenäoliselt vähem refaktoreerima ja hiljem koodi parandama.

Kas soovite tõesti olla see, kes vastutab kõigi tulevaste kodeerijate selle nutika väikese riimi lugemisrõõmu röövimise eest? Enamik kodeerijaid naeratas ja liikus edasi, eirates koodilõhna.

On ka juhtumeid, kui puutute kokku ülearuse kommentaariga. Kui kood on juba lihtne ja ilmne, pole kommentaari vaja lisada.

Nagu, ära tee seda jama:

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

Sellegipoolest on olukordi, kus ükskõik, mida te koodiga ise teete, on siiski vajalik selgituskommentaar.

Tavaliselt juhtub see siis, kui peate lisama mõne konteksti mitte-intuitiivsele lahendusele.

Siin on hea näide Lodashilt:

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

On ka aegu, kus - pärast palju mõtlemist ja katsetamist - selgub, et probleemi esmapilgul naiivne lahendus on tegelikult parim. Nendes stsenaariumides on peaaegu vältimatu, et mõni teine ​​kooder arvab, et on palju targem kui sina, ja hakkab koodiga jamama, et avastada, et kogu aeg oli sinu viis parim.

Mõnikord on see teine ​​kooder teie tulevane mina.

Sellistel juhtudel on kõige parem säästa kõigil aega ja piinlikkust ning jätta kommentaar.

Järgmine pilk-kommentaar haarab selle stsenaariumi suurepäraselt:

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

Jällegi on ülaltoodud pigem naljakas olemine kui abistamine. Kuid PEAKSite jätma kommentaari, hoiatades teisi, et nad ei näeks ilmselgelt näivat „paremat lahendust”, kui olete selle juba proovinud ja tagasi lükanud. Ja kui te seda teete, peaks kommentaar täpsustama, millist lahendust proovisite ja miks otsustasite selle vastu.

Siin on JavaScripti lihtne näide:

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

Kole

Niisiis, oleme vaadanud nii häid kui halbu, aga mis saab koledast?

Kahjuks on igas töös hetki, kus peate end pettuma ja kui kirjutate elamiseks koodi, võib olla ahvatlev see pettumus koodikommentaarides välja lasta.

Töötage piisavalt koodibaasidega ja leiate kommentaare, mis ulatuvad küünilistest ja masendavatest kuni tumedate ja alatute meeleoludeni.

Asjad, nagu näiliselt kahjutu ...

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

... otsesõnu

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

Need asjad võivad tunduda naljakad või aidata hetkel vabaneda pettumusest, kuid kui nad selle tootmiskoodiks muudavad, muudavad nad need kirjutanud kodeerija ja nende tööandja ebaprofessionaalseks ja kibedaks.

Ära tee seda.

Kui teile see artikkel meeldis, purustage palun mitu korda aplausiikoon, et see sõna leviks. Ja kui soovite veel selliseid asju lugeda, registreeruge palun allpool olevale iganädalasele Dev Mastery uudiskirjale.