Lähdekoodin kommenttityyppivihjeet ja parhaat käytännöt

Kehittäjät, jotka ovat viettäneet aikaa suuriin projekteihin, ymmärtävät koodikommenttien merkityksen. Kun rakennat monia ominaisuuksia samaan sovellukseen, asiat ovat yleensä monimutkaisia. On niin paljon tietobittejä, jotka sisältävät toimintoja, muuttuvia viittauksia, palautusarvoja, parametreja… miten odotetaan pysyvän?

Ei pitäisi olla yllätys, että koodisi kommentointi on välttämätöntä sekä soolo- että tiimiprojekteissa. Monet kehittäjät eivät kuitenkaan ole tietoisia siitä, miten mennä tähän prosessiin. Olen hahmotellut joitakin omia henkilökohtaisia ​​temppujani luoda siistit, alustetut koodikommentit. Standardit ja kommenttimallit vaihtelevat kehittäjien välillä - mutta lopulta sinun pitäisi pyrkiä kohti puhtaat ja luettavat kommentit selittää entisestään koodin sekava alue.

Meidän on aloitettava keskustelu eräistä kommenttien muotoilun eroista. Tämä antaa sinulle paremman käsityksen siitä, kuinka yksityiskohtaisesti voit tulla projektikoodilla. Myöhemmin tarjoan joitakin erityisiä vinkkejä ja esimerkkejä, joita voit aloittaa heti!

Kommenttityylit: yleiskatsaus

On huomattava, että esitetyt ajatukset ovat vain suuntaviivat kohti puhtaampia kommentteja. Yksittäiset ohjelmointikielet eivät sisällä ohjeita tai määrityksiä dokumentaation määrittämiseksi.

Nykypäivän kehittäjät ovat ryhmittäneet yhteen oman koodijärjestelmänsä muotoilun. Tarjoan muutamia tärkeimpiä tyylejä ja selvitän yksityiskohtaisesti niiden tarkoitusta.

Sisäinen kommentointi

Käytännössä jokainen ohjelmointikieli tarjoaa kommentit. Ne rajoittuvat yhden rivin sisältöön ja kommentoivat tekstiä vain tietyn kohdan jälkeen. Niinpä esimerkiksi C / C + +: ssa aloitat tämän linjan kommentin seuraavasti:

// aloittaa muuttujaluettelon var myvar = 1; 

Tämä sopii erinomaisesti sekoittamiseen koodiin muutaman sekunnin ajan selittää mahdollisesti sekava toiminta. Jos työskentelet paljon parametreja tai toiminnallisia puheluita, voit sijoittaa lähellä olevia kommentteja. Mutta edullisin käyttö on a yksinkertainen selitys pienille toiminnoille.

jos (callAjax ($ params)) // suoritti callAjaxin onnistuneesti käyttäjän parametreilla… code

Ennen kaikkea koodin pitäisi olla uudella rivillä avauskannattimen jälkeen. Muuten se kaikki jää samaan kommenttilinjaan! Vältä menemästä yli laidan koska sinun ei yleensä tarvitse nähdä yhden rivin kommentteja koko sivun alareunassa, mutta etenkin koodin sekoittumisten sekoittamiseksi, niitä on paljon helpompi pudottaa viime hetkellä.

Kuvailevat lohkot

Kun sinun on sisällytettävä suuri selitys yleensä, yksi linja ei tee temppua. Kaikissa ohjelmointialueissa on valmiiksi muotoiltuja kommenttimalleja. Kuvailevat lohkot nähdään erityisesti funktioiden ja kirjastotiedostojen ympärillä. Aina kun asetat uuden toiminnon, se on hyvä käytäntö lisää kuvaava lohko ilmoituksen yläpuolelle.

/ ** * @desc avaa modaalisen ikkunan, jossa näytetään viesti * @param string $ msg - näytettävä viesti * @return bool - menestys tai vika * / toiminto modalPopup ($ msg) … 

Yllä on yksinkertainen esimerkki kuvailevasta funktion kommentista. Olen kirjoittanut funktion oletettavasti JavaScript-kutsussa modalPopup joka ottaa yhden parametrin. Yllä olevissa kommenteissa olen käyttänyt phpDocumentorin kaltaista syntaksia, jossa jokaisella rivillä on a @ symboli, jota seuraa valittu avain. Nämä eivät vaikuta koodisi millään tavalla, joten voit kirjoittaa @kuvaus sijasta @desc ilman mitään muutoksia.

Näitä pieniä avaimia kutsutaan itse kommenttien tunnisteet jotka on dokumentoitu voimakkaasti verkkosivustolla. Voit vapaasti tehdä omia ja käyttää niitä haluamallasi tavalla koodissasi. Mielestäni ne auttavat pitämään kaiken virrassa Voin tarkistaa tärkeitä tietoja yhdellä silmäyksellä. Sinun pitäisi myös huomata, että olen käyttänyt sitä / * * / lohkomuotoinen kommentointimuoto. Tämä pitää kaiken paljon puhtaampaa kuin kaksinkertaisen viivan lisääminen jokaista riviä kohden.

Ryhmän / luokan kommentit

Toimintojen ja silmukoiden kommentoinnin lisäksi lohkoalueita ei käytetä yhtä usein. Missä todella tarvitset vahvaa estä kommentit ovat taustan asiakirjojen tai kirjastotiedostojen kärjessä. Jokaisella verkkosivustosi tiedostolla on helppo lähteä ulos ja kirjoittaa vankka dokumentaatio - näemme tämän käytännön useissa CMS-järjestelmissä, kuten WordPressissä.

Sivun yläosassa pitäisi olla kommentteja itse tiedostosta. Näin voit tarkista nopeasti, missä muokkaat kun työskentelet samanaikaisesti useilla sivuilla. Lisäksi voit käyttää tätä aluetta tietokanta tärkeimmistä toiminnoista, joita tarvitset luokkaan.

/ ** * @desc tämä luokka pitää toiminnot käyttäjän vuorovaikutuksessa * esimerkkejä ovat user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @hakuiset asetukset.php * / abstrakti luokka myWebClass  

Näet, että olen käyttänyt vain pientä malliluokkaa väärennökselle myWebClass koodi. Olen lisännyt joitakin metatietoja nimi ja sähköpostiosoite. Kun kehittäjät kirjoittavat avoimen lähdekoodin, tämä on yleensä hyvä käytäntö, joten toiset voivat ottaa sinuun yhteyttä saadakseen tukea. Tämä on myös hyvä tapa työskennellä suuremmissa kehitysryhmissä.

Tunniste @vaaditaan en ole nähnyt sitä, mitä olen käyttänyt muualla. Olen pysynyt mukana muutamissa projekteissani vain sivuilla, joissa olen mukauttanut paljon menetelmiä. Aina kun lisäät sivuja tiedostoon, niiden tulee tulla ennen kuin lähetät koodin. Joten näiden tietojen lisääminen pääluokan kommenttilohkoon on hyvä tapa muista, mitä tiedostoja tarvitaan.

Front-end-koodin kommentointi

Nyt kun olemme käsitelleet 3 tärkeää kommenttimallia, tarkastellaan muutamia muita esimerkkejä. On monia frontend-kehittäjiä, jotka ovat siirtyneet staattisesta HTML: stä jQuery- ja CSS-koodiksi. HTML-kommentit eivät ole yhtä tarkoituksenmukaisia ​​kuin ohjelmointisovellukset, mutta kun kirjoitat tyyli-kirjastoja ja sivun komentosarjoja, asiat voivat ajan mittaan sotkea.

JavaScript noudattaa perinteisempää kommentointimenetelmää, joka on samanlainen kuin Java, PHP ja C / C++. CSS käyttää vain lohkon ja tähdellä rajattuja lohkomuotoisia kommentteja. Muista, että kommentit näkyvät avoimesti kävijöillesi, koska kumpikaan CSS tai JS ei jäsennä palvelinpuolta, mutta jompikumpi näistä menetelmistä toimii erinomaisesti jättääksesi informatiiviset tidbit takaisin koodiin.

Erityisesti CSS-tiedostojen hajottaminen voi olla urakka. Olemme kaikki tietoisia siitä, että jätät sisäisen kommentin selittämään Internet Explorerin tai Safarin korjauksen. Mutta uskon, että CSS-kommentteja voidaan käyttää tasolla jQuery ja PHP käyttää niitä. Lyömme tyyliryhmien luomiseen ennen kuin otat käyttöön joitakin yksityiskohtaisia ​​vinkkejä koodin kommentoimiseen.

CSS-tyyliryhmät

Niille, jotka ovat jo vuosia suunnitelleet CSS: ää, se on lähes toinen. Muistit hitaasti kaikki ominaisuudet, syntaksit ja rakentaa omaa järjestelmäluettelon järjestelmää. Oma työni kautta olen luonut sen, mitä kutsun ryhmittymä yhdistää samanlaiset CSS-lohkot yhteen alueeseen.

Kun palaat CSS: n muokkaamiseen, löydän helposti mitä tarvitsen muutamassa sekunnissa. Tapa, jolla päätät ryhmitellä tyylejä, on täysin sinun tehtäväsi, ja se on tämän järjestelmän kauneus. Minulla on muutamia esiasetettuja standardeja, jotka olen esittänyt alla:

• @resets - oletusselaimen marginaalien, pehmusteen, fonttien, värien jne. poistaminen.
• @fonts - kappaleet, otsikot, lohkot, linkit, koodi
• @navigation - tärkeimmät verkkosivuston navigointilinkit
• @layout - kääre, kontti, sivupalkit
• @header & @footer - nämä voivat vaihdella suunnittelusi mukaan. Mahdollisia tyylejä ovat linkit ja järjestämättömät luettelot, alatunnisteiden sarakkeet, otsikot, aliverkot

Kun ryhmität tyylitaulukoita, olen löytänyt sen merkintäjärjestelmä voi auttaa paljon. Toisin kuin PHP tai JavaScript, käytän yhtä @ryhmä tunniste, jota seuraa luokka tai avainsanat. Olen sisällyttänyt 2 alla olevaa esimerkkiä, jotta voit tuntea, mitä tarkoitan.

/ ** @group footer * / #footer tyylejä…

/ ** @group alatunniste, pienet fontit, sarakkeet, ulkoiset linkit ** / 

Vaihtoehtoisesti voit lisätä hieman lisätietoa kussakin kommenttiyksikössä. Päätän pitää asiat yksinkertaisina ja yksinkertaisina joten tyylitaulukot ovat helposti kuorittavissa. Kommentoimalla on kyse dokumentoinnista niin kauan kuin ymmärrätte kirjallisesti, että on hyvä mennä!

4 Vinkkejä paremman kommentin muotoiluun

Olemme käyttäneet tämän artikkelin ensimmäistä puoliskoa tarkastelemalla eri koodin kommentointimuotoja. Tarkastellaan nyt joitakin yleisiä vinkkejä, joiden avulla voit pitää koodisi puhtaana, organisoituna ja helposti ymmärrettävänä.

1. Pidä kaikki luettavissa

Joskus kehittäjinä unohdamme sen kirjoitamme kommentteja ihmisille lukea. Kaikki ymmärrettävät ohjelmointikielet on rakennettu koneille, joten se voi olla ikävä muuntaminen yksinkertaiseksi kirjoitetuksi tekstiksi. On tärkeää huomata, että emme ole täällä kirjoittamassa korkeakoulutason tutkimustyötä, mutta vain jättää vinkkejä!

toiminto getTheMail () // code here rakentaa sähköposti / * run-koodin, jos mukautettu sendMyMail () -toimintopuhelu palauttaa oikean etsinnän sendMyMail () /libs/mailer.class.php: ssä, jos tarkistamme, täyttääkö käyttäjä kaikki kentät ja viesti lähetetään! * / if (sendMyMail ()) paluu totta; // pidä paikkansa ja näytä näytön menestys

Jopa vain pari sanaa parempi kuin ei mitään. Kun palaat muokattavaksi ja projektin parissa tulevaisuudessa, on usein yllättävää, kuinka paljon unohdat. Koska et katso päivittäin samoja muuttujia ja toiminimiä, unohdat hitaasti enemmistön koodista. Näin voit älä koskaan jätä liikaa kommentteja! Mutta voit jättää liian monta huonoa kommenttia.

Yleisenä nyrkkisääntönä, kestää jonkin aikaa, ennen kuin kirjoitat. Kysy itseltäsi mikä on kaikkein hämmentävin ohjelma ja miten voit parhaiten selittää sen “tutti” Kieli? Harkitse myös miksi kirjoitat koodia juuri niin kuin olet.

Jotkin kaikkein hämmentävimmistä virheistä ilmestyvät, kun unohdat räätälöidyn (tai kolmannen osapuolen) toimintojen tarkoituksen. Jätä kommenttireitti takaisin joihinkin muihin tiedostoihin jos tämä auttaa sinua muistamaan toiminnallisuuden helpottamisen.

2. Vähennä jotakin tilaa!

En voi korostaa tarpeeksi, kuinka tärkeää välilyönti voi olla. Tämä tapahtuu kaksinkertaisesti totta PHP: lle ja Ruby-kehittäjille, jotka työskentelevät massiivisilla sivustoilla, joissa on satoja tiedostoja. Tulet tuijottamaan tätä koodia koko päivän! Eikö olisi hienoa, jos voisit vain ohittaa tärkeät alueet?

$ dir1 = "/ home /"; // asetettu pääkansion hakemisto $ myCurrentDir = getCurDirr (); // aseta nykyinen käyttäjähakemisto $ userVar = $ get_username (); // nykyisen käyttäjänimi

Yllä olevassa esimerkissä huomaat ylimääräisen pehmusteen, jonka olen asettanut kommenttien ja koodien väliin kullekin riville. Kun selaat tiedostoja, tämä kommentointityyli on selvästi erottuvat. Se tekee virheitä ja korjaa koodin satoja kertoja helpommin kun muuttuvat lohkot ovat niin puhdas.

Voit suorittaa samanlaisen tehtävän koodin sisällä toiminnon sisällä, jossa olet hämmentynyt siitä, miten se toimii, mutta tämä menetelmä lopulta sekoittaa koodisi inline-kommenteilla, ja se on täsmälleen päinvastainen! Suosittelen tässä tilanteessa lisäämällä suuri lohkoviivan kommentti logiikan alueen ympärille.

$ (asiakirja) .ready (toiminto () $ ('. sub'). piilota (); // piilota alihakemisto sivutiedostossa / ** tarkista napsautustapahtuma. toiminta niin, että sivu ei muutu napsauttamalla pääset .itm-vanhempaan elementtiin, jota seuraa seuraava .sub-luettelo, jolloin voit vaihtaa avoimen / sulkeutuvan ** / $ ('. itm a'). live ('click', toiminto (e ) e.preventDefault (); $ (tämä) .parent () seuraava ('. sub'). slideToggle ('fast');););

Tämä on pieni jQuery-koodi, joka kohdistuu alivalikon liukuvalikkoon. Ensimmäinen kommentti selittää, miksi piilotamme kaikki .sub luokat. Live-click-tapahtuman käsittelijän yläpuolella olen käyttänyt lohkokommenttia ja kaikki kirjallisesti samaan kohtaan. Tämä tekee asiat kauniimmin kuin juoksevat kappaleet - erityisesti muille, jotka lukevat kommenttisi.

3. Kommentoi koodauksen aikana

Oikean välimatkan ohella tämä voi olla yksi parhaista tavoista päästä. Kukaan ei halua palata ohjelmansa jälkeen sen jälkeen, kun se on työskennellyt ja dokumentoinut jokaisen kappaleen. Useimmat meistä eivät edes halua palata takaisin ja dokumentoida sekavia alueita! Se todella vie paljon työtä.

Mutta jos voit kirjoittaa kommentteja koodauksen aikana kaikki on edelleen tuore mielessäsi. Tyypillisesti kehittäjät tarttuvat ongelmaan ja huuhtovat webin helpoin ratkaisu. Kun osaat Eureka-hetkeen ja ratkaista tällainen ongelma, on yleensä selvä hetki, jossa ymmärrät aiemmat virheet. Tämä olisi paras aika jättää avoimet ja rehelliset kommentit koodistasi.

Lisäksi tämä antaa sinulle käytännön tottua kommentoimaan kaikkia tiedostoja. Palaa aikaa, joka tarvitaan palataksesi ja selvittämään, miten jotain toimii, on paljon suurempi, kun olet jo rakentanut toiminnon. Sekä tulevaisuuden itsesi että joukkuetoverisi kiittävät, että jätit kommentit etukäteen.

4. Buggy-virheiden käsittely

Emme voi kaikki istua tietokoneen edessä tuntien kirjoittamista varten. Luulen, että voimme yrittää, mutta jossain vaiheessa meidän täytyy nukkua! Sinun on todennäköisesti osattava järjestää koodisi päiväsi kanssa, ja joitakin ominaisuuksia on vielä rikki. Tässä tilanteessa on tärkeää, että te jätä pitkiä, yksityiskohtaisia ​​kommentteja siitä, mistä jätit asiat pois.

Jopa tuoreen yöunen jälkeen saatat olla yllättynyt siitä, kuinka vaikeaa on saada takaisin koodauksen keinuun. Jos esimerkiksi rakennat kuvien lataussivun ja sinun on jätettävä se loppuunsaattamatta, sinä pitäisi kommentoida, missä prosessissa jätit. Ovatko kuvat ladattavissa ja tallennettuina muistiin? Tai ehkä niitä ei edes tunnisteta latauslomakkeessa, tai ehkä ne eivät näy oikein sivun lataamisen jälkeen.

Virheiden kommentointi on tärkeää kahdesta syystä. Ensin voit helposti poimia, jos jätit ja yritä uudelleen tuoreena korjata ongelma. Ja toiseksi voit erotettava sivustosi live-versio ja testauspaikat. Muista, että kommentteja tulisi käyttää selitä, miksi teet jotain, ei juuri sitä, mitä se tekee.

johtopäätös

Web-sovellusten ja ohjelmistojen kehittäminen on tyydyttävä käytäntö, vaikkakin vaikea. Jos olet yksi harvoista kehittäjistä, jotka todella ymmärtävät rakennusohjelmistoja, on tärkeää kypsyä koodaustekniikalla. Kuvailevien kommenttien jättäminen on vain hyvä käytäntö pitkällä aikavälillä, ja et todennäköisesti koskaan katuta sitä!

Jos sinulla on ehdotuksia selkeämmistä koodikommenteista, ilmoita asiasta keskustelualueella!