Kommenttien kirjoittaminen koodiin: hyvä, huono ja ruma.

Pysäytä minut, jos olet kuullut tämän aiemmin ...

"Hyvä koodi on itse dokumentoiva."

20 vuotta kirjoittaessani koodia elantoni, tämä on yksi lause, jonka olen kuullut eniten.

Se on klisee.

Ja kuten monilla kliseillä, sillä on totuuden ydin. Mutta tätä totuutta on käytetty niin väärin, että useimmilla lauseen lausuvilla ihmisillä ei ole aavistustakaan, mitä se todella tarkoittaa.

Onko se totta? Kyllä .

Tarkoittaako se, että sinun ei pitäisi koskaan kommentoida koodiasi? Ei .

Tässä artikkelissa tarkastelemme hyviä, huonoja ja rumuja koodin kommentoimisessa.

Ensinnäkin on todella kaksi erityyppistä koodikommenttia. Kutsun heitä dokumentointikommenteiksi ja selvennyskommenteiksi .

Dokumentaation kommentit

Dokumentaatiokommentit on tarkoitettu kaikille, jotka todennäköisesti kuluttavat lähdekoodiasi, mutta eivät todennäköisesti lue sitä. Jos rakennat kirjastoa tai kehystä, jota muut kehittäjät käyttävät, tarvitset jonkinlaisen API-dokumentaation.

Mitä kauemmin API-dokumentaatio on poistettu lähdekoodista, sitä todennäköisemmin se on vanhentunut tai epätarkka ajan myötä. Hyvä strategia tämän lieventämiseksi on upottaa dokumentaatio suoraan koodiin ja purkaa se sitten työkalulla.

Tässä on esimerkki suositun Lodash-nimisen JavaScript-kirjaston dokumentointikommentista.

Jos vertaat näitä kommentteja heidän online-asiakirjoihin, näet, että ne ovat tarkalleen sopivia.

Jos kirjoitat dokumentaatiokommentteja, varmista, että ne noudattavat yhtenäistä standardia ja että ne ovat helposti erotettavissa kaikista sisäisistä selvennyskommenteista, jotka haluat ehkä lisätä. Joitakin suosittuja ja hyvin tuettuja standardeja ja työkaluja ovat JSDoc for JavaScript, DocFx for dotNet ja JavaDoc for Java.

Tämäntyyppisten kommenttien haittapuoli on, että ne voivat tehdä koodistasi erittäin "meluisan" ja vaikeampaa lukea kaikille, jotka ovat aktiivisesti mukana sen ylläpidossa. Hyvä uutinen on, että useimmat koodieditorit tukevat "koodin taittamista", jonka avulla voimme tiivistää kommentit, jotta voimme keskittyä koodiin.

Selvennykset

Selvennyskommentit on tarkoitettu kaikille (myös tulevalle itsellesi), jonka on ehkä ylläpidettävä, muokattava tai laajennettava koodiasi.

Usein selventävä kommentti on koodihaju. Se kertoo sinulle, että koodisi on liian monimutkainen. Sinun tulisi pyrkiä poistamaan selvennyskommentit ja yksinkertaistamaan koodia, koska "hyvä koodi on itse dokumentoiva".

Tässä on esimerkki huonoista - vaikkakin hyvin viihdyttävistä - selvennyskommenteista.

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

Sen sijaan, että koristelisi hieman hämmentävää lausetta älykkäällä riimillä - ei amphibrach-dimetrillä , kirjoittajalla olisi ollut paljon parempi viettää aikaa funktioon, joka tekee koodista itsensä helpommin luettavan ja ymmärrettävän. Ehkä nimetty funktio, removeCurlyBracesjota kutsutaan toisesta funktiosta nimeltä sanitizeInput?

Älkää ymmärtäkö minua väärin, on aikoja - varsinkin kun törmäät murskaavaan työmäärään - jossa vähän huumoria voi olla hyvä sielulle. Mutta kun kirjoitat hauska kommentti korvaamaan huono koodi, se tosiasiassa tekee ihmisistä vähemmän todennäköisiä refraktoida ja korjata koodi myöhemmin.

Haluatko todella olla vastuussa siitä, että ryöstät kaikilta tulevilta koodaajilta ilon lukea sitä fiksua pientä riimiä? Useimmat koodaajat naureskelivat ja siirtyivät eteenpäin ohittamatta koodihaju.

On myös tapauksia, joissa törmäät tarpeettomaan kommenttiin. Jos koodi on jo yksinkertainen ja ilmeinen, kommenttia ei tarvitse lisätä.

Kuten, älä tee tätä hölynpölyä:

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

Silti on tilanteita, joissa riippumatta siitä, mitä teet itse koodille, selityskommentti on silti perusteltu.

Yleensä tämä tapahtuu, kun sinun on lisättävä konteksti ei-intuitiiviseen ratkaisuun.

Tässä on hyvä esimerkki Lodashista:

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

On myös tilanteita, joissa - paljon miettimisen ja kokeilun jälkeen - käy ilmi, että näennäisesti naiivi ratkaisu ongelmaan on oikeastaan ​​paras. Näissä skenaarioissa on melkein väistämätöntä, että joku muu kooderi pääsee ajattelemaan olevansa paljon älykkäämpiä kuin sinä, ja alkaa sekaantua koodiin vain huomatakseen, että matkasi oli paras tapa koko ajan.

Joskus tuo toinen kooderi on tulevasi itsesi.

Näissä tapauksissa on parasta säästää kaikille aikaa ja hämmennystä ja jättää kommentti.

Seuraava mallikommentti vangitsee tämän skenaarion täydellisesti:

/**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älleen, yllä on enemmän hauskaa kuin hyödyllistä. Mutta sinun PITÄ jättää kommentti, joka varoittaa muita olemasta etsimässä jotakin näennäisesti ilmeistä "parempaa ratkaisua", jos olet jo yrittänyt hylätä sen. Ja kun teet, kommentissa tulisi määritellä, mitä ratkaisua yritit ja miksi päätit sitä vastaan.

Tässä on yksinkertainen esimerkki JavaScriptistä:

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

Ruma

Joten olemme tarkastelleet hyviä ja huonoja, mutta entä ruma?

Valitettavasti missä tahansa työpaikassa on ajoittain turhautuneita, ja kun kirjoitat elinkoodia, voi olla houkuttelevaa tuoda turhautuminen koodikommentteihin.

Työskentele riittävän koodipohjan kanssa ja kohtaat kommentteja, jotka vaihtelevat kyynisistä ja masentavista tummiin ja ilkeisiin.

Sellaiset asiat kuin näennäisesti vaaraton…

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

… Suorastaan ​​tarkoittaa

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

Nämä asiat saattavat tuntua hauskoilta tai voivat auttaa vapauttamaan hieman turhautumista tällä hetkellä, mutta kun he tekevät siitä tuotantokoodin, ne tekevät heidän kirjoittaneen kooderin ja työnantajan näyttävän epäammattimaiselta ja katkeralta.

Älä tee tätä.

Jos pidit tästä artikkelista, hajota suosionosoituskuvake useita kertoja levittääksesi sanaa. Ja jos haluat lukea lisää tällaisia ​​juttuja, kirjaudu alla olevaan viikoittaiseen Dev Mastery -uutiskirjeeseeni.