Avota koda komentāru veidošanas padomi un paraugprakse
Izstrādātāji, kas ir pavadījuši kādu laiku lielos projektos, saprot kodu komentāru nozīmi. Veidojot daudzas funkcijas vienā lietojumprogrammā, lietas parasti kļūst sarežģītas. Ir tik daudz datu bitu, kas ietver funkcijas, mainīgās atsauces, atgriešanās vērtības, parametrus ... kā jūs sagaidāt, lai turpinātu?
Nav nekāds pārsteigums, ka jūsu koda komentēšana ir svarīga gan solo, gan komandu projektos. Bet daudzi izstrādātāji nezina, kā rīkoties šajā procesā. Es esmu izklāstījis dažus savus personīgos trikus veidojot kārtīgus, formatētus kodu komentārus. Standarti un komentāru veidnes dažādiem izstrādātājiem atšķirsies, bet galu galā jums vajadzētu censties tīri un lasāmi komentāri lai vēl vairāk paskaidrotu jūsu koda mulsinošās jomas.
Mums jāsāk diskusijas par dažām komentāru formatēšanas atšķirībām. Tas dos jums labāku priekšstatu par to, cik detalizēti jūs varat kļūt par projekta kodu. Pēc tam es piedāvāšu dažus konkrētus padomus un piemērus, kurus jūs varat sākt izmantot nekavējoties!
Komentāru stili: pārskats
Jāatzīmē, ka šīs idejas ir tikai pamatnostādnes uz tīrākiem komentāriem. Atsevišķās programmēšanas valodās nav izklāstītas vadlīnijas vai specifikācijas, kā iestatīt dokumentāciju.
Tas nozīmē, ka mūsdienu attīstītāji ir apvienojušies, lai formatētu savu kodu komentēšanas sistēmu. Es piedāvāšu dažus galvenos stilus un sīki izklāstīšu to mērķi.
Komentāri
Praktiski tiek piedāvāti visi programmēšanas valodas komentāri. Tie attiecas tikai uz vienas rindas saturu un komentē tekstu tikai pēc noteikta punkta. Tātad, piemēram, C / C + + sākat inline komentāru šādi:
// sākt mainīgo sarakstu var myvar = 1;
Tas ir ideāli piemērots dažu sekunžu kodēšanai izskaidrot, iespējams, neskaidru funkcionalitāti. Ja strādājat ar daudziem parametriem vai funkciju izsaukumiem, tuvumā var novietot vairākus komentārus. Bet visizdevīgākais lietojums ir a vienkāršs izskaidrojums mazām funkcijām.
ja (callAjax ($ params)) // veiksmīgi darbina callAjax ar lietotāja parametriem ... kodu
Vispirms paziņojumam par kodu ir jābūt jaunā rindā pēc atvēršanas kronšteina. Pretējā gadījumā tas viss tiktu uztverts vienā un tajā pašā komentāru rindā! Izvairieties no braukšanas pāri bortam jo jums parasti nav nepieciešams redzēt vienas rindiņas komentārus visu jūsu lapas leju, bet jo īpaši, lai sajauktu jūsu koda krustojumus, tie ir daudz vieglāk nolaisties pēdējā brīdī.
Aprakstošie bloki
Kad jums ir nepieciešams iekļaut plašu skaidrojumu, parasti viens līnijpārvadātājs to nedarīs. Katrā programmēšanas jomā tiek izmantotas iepriekš formatētas komentāru veidnes. Aprakstošie bloki visbiežāk ir redzamas funkcijas un bibliotēkas faili. Ikreiz, kad iestatāt jaunu funkciju, tā ir laba prakse virs deklarācijas pievienojiet aprakstošu bloku.
/ ** * @ desc atver modālu logu, lai parādītu ziņojumu * @param string $ msg - parādāmā ziņa * @return bool - veiksme vai neveiksme * / funkcija modalPopup ($ msg) …
Iepriekš ir vienkāršs aprakstoša funkcijas komentāra piemērs. Esmu rakstījis funkciju, ko, iespējams, sauc par JavaScript modalPopup kas ņem vienu parametru. Iepriekš minētajos komentāros es esmu izmantojis sintaksi, kas ir līdzīga phpDocumentor, kur pirms katras rindas ir a @ simbols, kam seko izvēlētais taustiņš. Tie nekādā veidā neietekmēs jūsu kodu, lai jūs varētu rakstīt @ apraksts tā vietā @desc bez jebkādām izmaiņām.
Šie mazie taustiņi tiek aicināti komentāru tagi kas ir dokumentēti lielā mērā tīmekļa vietnē. Jūtieties brīvi, lai izveidotu savu un izmantotu tos, kā jūs vēlaties, savā kodā. Es uzskatu, ka viņi palīdz saglabāt visu plūstošo Es varu īsumā pārbaudīt svarīgu informāciju. Jums vajadzētu arī pamanīt, ka esmu izmantojis / * * / bloku stila komentēšanas formāts. Tas viss notiks daudz tīrāku nekā pievienojot dubultu slīpsvītru, kas sākas katrā rindā.
Grupas / klases komentāri
Papildus funkciju un cilpu komentēšanai, bloku apgabali netiek izmantoti tik bieži. Kur jums tiešām ir nepieciešams spēcīgs bloķēt komentārus ir jūsu backend dokumentu vai bibliotēkas failu priekšā. Katram jūsu tīmekļa vietnes failam ir viegli iet visu tekstu un uzrakstīt cieto dokumentāciju - mēs varam redzēt šo praksi daudzās CMS, piemēram, WordPress..
Jūsu lapas augšējai daļai vajadzētu būt komentāriem par pašu failu. Tādā veidā jūs varat ātri pārbaudiet, kur rediģējat vienlaikus strādājot ar vairākām lapām. Turklāt varat izmantot šo apgabalu kā datu bāze par svarīgākajām funkcijām, kas jums būs nepieciešama no klases.
/ ** * @ desc šai klasei būs funkcijas lietotāja mijiedarbībai * piemēri ietver lietotāja_pāri (), lietotāja_lietotājvārds (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @irquired settings.php * / abstrakta klase myWebClass
Jūs varat redzēt, ka esmu izmantojis tikai nelielu izlases klasi viltībai myWebClass kodu. Esmu pievienojis kādu meta informāciju ar manu vārdu un e-pasta adresi kontaktam. Kad izstrādātāji raksta atvērtā pirmkoda kodu, tas parasti ir laba prakse, lai citi varētu ar jums sazināties, lai saņemtu atbalstu. Tā ir arī stabila metode, strādājot lielākās attīstības komandās.
Tag @ pieprasīts nav kaut kas, ko esmu redzējis citur. Esmu saglabājis formātu dažos manos projektos, tikai tajās lapās, kurās esmu pielāgojis daudzas metodes. Ikreiz, kad jūs ievietojat lapas failā, tiem nākas pirms jebkāda koda izejas. Tāpēc šo detaļu pievienošana galvenās klases komentāru blokam ir labs veids, kā atcerieties, kādi faili ir nepieciešami.
Komentāri par priekšpuses kodu
Tagad, kad mēs esam iekļāvuši 3 svarīgas komentāru veidnes, apskatīsim dažus citus piemērus. Ir daudzi frontendu izstrādātāji, kuri ir pārvietoti no statiskās HTML uz jQuery un CSS kodu. HTML komentāri nav tik mērķtiecīgi, salīdzinot ar programmēšanas programmām, bet, rakstot stila bibliotēkas un lapu skriptus, laika gaitā lietas var kļūt netīrs.
JavaScript seko tradicionālākām piezīmēm, kas ir līdzīgas Java, PHP un C / C++. CSS izmanto tikai bloku stila komentārus, ko apzīmē slīpsvītra un zvaigznīte. Atcerieties, ka jūsu apmeklētājiem tiks atklāti komentāri, jo ne CSS, ne JS netiek parsēta servera pusē, bet kāda no šīm metodēm lieliski darbojas, lai kodā atstātu informatīvus sīkumus, lai atgrieztos.
Konkrēti CSS failu sadalīšana var būt sīki mājas darbi. Mēs visi esam pazīstami ar to, ka paliekim inline komentāru, lai izskaidrotu Internet Explorer vai Safari labojumu. Bet es uzskatu, ka CSS komentārus var izmantot līmenī, kurā jQuery un PHP tos izmanto. Pirms pieskaries dažiem detalizētiem padomiem par kodu komentēšanu, ienāciet veidot stila grupas.
CSS stila grupas
Tiem, kuri jau vairākus gadus ir izstrādājuši CSS, tas ir gandrīz otrs. Jūs lēnām atceraties visas īpašības, sintaksi un veidojiet savu sistēmu stilu lapām. Ar savu darbu esmu izveidojis to, ko es aicinu grupēšana savienot līdzīgus CSS blokus vienā apgabalā.
Atgriežoties atpakaļ, rediģējot CSS, dažu sekunžu laikā es varu viegli atrast to, kas man nepieciešams. Kā jūs izvēlaties, lai grupētu stilus, tas ir atkarīgs no jums, un tā ir šīs sistēmas skaistums. Man ir daži iepriekš noteiktie standarti, kurus esmu izklāstījis tālāk:
- @resets - noklusējuma pārlūka margu, polsterējumu, fontu, krāsu uc atņemšana.
- @fonts - rindkopas, virsraksti, bloknotes, saites, kods
- @navigācija - galvenās tīmekļa vietnes navigācijas saites
- @layout - iesaiņojums, konteiners, sānjoslas
- @header & @footer - tie var atšķirties atkarībā no jūsu dizaina. Iespējamie stili ietver saites un neierobežotus sarakstus, kājenes kolonnas, virsrakstus, apakšnavārdus
Grupējot stillapas, es esmu atradis iezīmēšanas sistēma var daudz palīdzēt. Tomēr atšķirībā no PHP vai JavaScript es izmantoju vienu @grupa tagu, kam seko kategorija vai atslēgvārdi. Es esmu pievienojis 2 piemērus, lai jūs varētu justies par to, ko es domāju.
/ ** @grupas kājene * / #footer stili ...
/ ** @grupu kājene, mazi fonti, kolonnas, ārējās saites ** /
Katrā komentāru blokā jūs varat arī pievienot nedaudz sīkāku informāciju. Es izvēlos saglabāt lietas vienkāršas un vienkāršas tāpēc stilu tabulas ir viegli nosmelt. Komentējot, viss attiecas uz dokumentāciju, tik ilgi, kamēr jūs saprotat rakstīšanu, kas ir labi iet!
4 padomi, kā uzlabot komentārus
Šī panta pirmajā pusē mēs esam pavadījuši dažādus kodu komentēšanas formātus. Tagad apspriedīsim dažus vispārējus padomus, kā saglabāt jūsu kodu tīru, organizētu un viegli saprotamu.
1. Saglabājiet visu lasāmu
Dažreiz kā izstrādātāji to aizmirstam mēs rakstām komentārus cilvēkiem lasīt. Visas programmēšanas valodas, ko mēs saprotam, ir veidotas mašīnām, tāpēc var būt garlaicīgs, lai pārvērstu parastā rakstā. Ir svarīgi atzīmēt, ka mēs neesam šeit, lai uzrakstītu koledžas līmeņa pētījumu, bet vienkārši atstājot padomus!
funkcija getTheMail () // kods šeit veidos e-pastu / * palaist kodu, ja mūsu pasūtījuma sendMyMail () funkciju zvans atgriež patiesu atrast sendMyMail () /libs/mailer.class.php, mēs pārbaudām, vai lietotājs aizpilda visus laukus un ziņojums tiek nosūtīts! * / ja (sendMyMail ()) atgriezties taisnība; // saglabāt patiesu un parādīt ekrāna panākumus
Pat tikai pāris vārdi labāk nekā nekas. Atgriežoties pie rediģēšanas un strādājot pie projektiem nākotnē, tas bieži ir pārsteidzoši, cik daudz jūs aizmirsīsiet. Tā kā jūs katru dienu neredzat tos pašus mainīgos un funkciju nosaukumus, jūs mēdzat pamazām aizmirst lielāko daļu sava koda. Tādējādi jūs varat nekad neatstājiet pārāk daudz komentāru! Bet jūs varat atstāt pārāk daudz sliktu komentāru.
Kā vispārējs īkšķis, pirms rakstīšanas pauzēt un pārdomāt. Jautājiet sev kas ir visvairāk mulsinoši par programmu un kā jūs to varat vislabāk izskaidrot “manekens” valoda? Ņemiet vērā arī kāpēc jūs rakstāt kodu tieši tā, kā jūs esat.
Dažas no mulsākajām kļūdām parādās, kad esat aizmirsis pasūtījuma (vai trešās puses) funkciju mērķi. Atstājiet komentāru trajektoriju, kas ved atpakaļ uz pārējiem failiem ja tas palīdzēs jums atcerēties funkcionalitāti vieglāk.
2. Atbrīvojiet kādu vietu!
Es nevaru pietiekami uzsvērt, cik svarīgi atstarpes var būt. Tas notiek divkārši PHP un Ruby izstrādātājiem, kas strādā pie masīvām vietnēm ar simtiem failu. Jūs visu dienu skatāties šo kodu! Vai tas nebūtu lieliski, ja jūs varētu vienkārši nokrist līdz svarīgajām jomām?
$ dir1 = "/ home /"; // iestatīta galvenā mājas direktorija $ myCurrentDir = getCurDirr (); // iestatiet pašreizējo lietotāja direktoriju $ userVar = $ get_username (); // pašreizējā lietotāja lietotājvārds
Iepriekš minētajā piemērā jūs pamanīsiet, ka katrā rindā es esmu ievietojis papildu ieliktņus starp komentāriem un kodu. Ritinot failus, šis komentēšanas stils būs skaidri izceļas. Tā padara kļūdas un labo kodu simtiem reižu vieglāk ja mainās bloki tīrs.
Jūs varētu veikt līdzīgu uzdevumu ar kodu iekšpusē funkcijas, kur jūs esat sajaukt par to, kā tā darbojas, bet šī metode galu galā jucekli jūsu kodu ar inline komentārus, un tas ir tieši pretējs kārtīgi! Es iesaku šajā scenārijā pievienojot lielu bloka līniju komentāru ap loģikas jomu.
$ (dokuments). jau (funkcija () $ ('. sub'). hide (); // paslēpt sub-navigāciju pageload / ** pārbaudiet klikšķa notikumu enkurā .itm div novērst noklusējuma saiti darbība, lai lapa netiktu mainīta uz klikšķa, lai piekļūtu .itm vecākajam elementam, kam seko nākamais .sub saraksts, lai pārslēgtu atvērtu / aizvērtu ** / $ ('. itm a'). ) e.preventDefault (); $ (this) .parent () nākamā (“. sub”). slideToggle (“fast”););); Šī ir neliela jQuery koda bāze, kas vērsta uz apakšizvēlnes bīdāmo navigāciju. Pirmais komentārs ir nepārprotams, lai izskaidrotu, kāpēc mēs slēpjam visu .sub klases. Virs tiešā klikšķa notikumu apstrādātāja esmu izmantojis bloka komentāru un tajā pašā punktā norādīja visus rakstus. Tas padara lietas labāku, nevis izpilda rindkopas - īpaši citiem, kas lasa jūsu komentārus.
3. Komentēt kodēšanas laikā
Kopā ar pareizu atstarpi tas var būt viens no labākajiem ieradumiem. Neviens nevēlas atgriezties savās programmās pēc tam, kad tas strādā un dokumentē katru gabalu. Lielākā daļa no mums pat nevēlas atgriezties un dokumentēt neskaidras jomas! Tas patiešām aizņem daudz darba.
Bet, ja jūs varat rakstīt komentārus, kamēr esat kodējis viss jūsu prātā joprojām būs svaigs. Raksturīgi, ka izstrādātāji iestrēgos problēmu un vieglāk risinās tīmekli. Kad nokļūsiet Eureka brīdī un atrisināt šādu problēmu, parasti ir skaidrs brīdis, kurā jūs saprotat savas iepriekšējās kļūdas. Tas būtu labakais laiks atstāt atvērtus un godīgus komentārus par jūsu kodu.
Turklāt tas dos jums praksi pierast pie visiem jūsu failiem. Laiks, kas nepieciešams, lai atgrieztos un izdomātu, kā kaut kas darbojas, ir daudz lielāks pēc tam, kad esat jau izveidojis funkciju. Gan jūsu nākotne, gan jūsu komandas biedri pateicos par komentāru atstāšanu pirms laika.
4. Darbs ar kļūdām
Mēs nevaram visu laiku sēdēt datora priekšā, lai rakstītu kodu. Es domāju, ka mēs varam mēģināt, bet kādā brīdī mums ir jāgaida! Iespējams, jums būs jāapvieno ceļi ar jūsu koda datumu ar dažām funkcijām. Šajā scenārijā ir svarīgi, lai jūs atstājiet garus, detalizētus komentārus par to, kur jūs atstājāt lietas.
Pat pēc svaigas nakts miega jums var būt pārsteigts, cik grūti ir atgriezties kodēšanas svārstībās. Piemēram, ja veidojat attēlu augšupielādes lapu un jums tas ir jāatstāj pabeigts, jūs vajadzētu komentēt, kurā procesā jūs atstājāt. Vai attēli tiek augšupielādēti un tiek saglabāti atmiņā? Vai varbūt tie nav pat atzīti augšupielādes formā, vai varbūt tie netiek parādīti pareizi lapā pēc augšupielādes.
Kļūdu komentēšana ir svarīga divu iemeslu dēļ. Vispirms jūs varat viegli uzņemt, kur jūs atstājāt un mēģiniet vēlreiz svaigā veidā novērst problēmu (-as). Un, otrkārt, jūs varat nošķiriet vietnes tiešraides versiju un pārbaudes laukumus. Atcerieties, ka piezīmes ir jāizmanto paskaidrojiet, kāpēc jūs kaut ko darāt, nav tieši tas, ko tas dara.
Secinājums
Tīmekļa lietotņu un programmatūras izstrāde ir atbilstoša prakse, lai arī tā ir sarežģīta. Ja jūs esat viens no nedaudzajiem izstrādātājiem, kas patiesi saprot ēku programmatūru, tad ir svarīgi nobriest ar savu kodēšanas prasmi. Atstājot aprakstošus komentārus, tā ir tikai laba prakse ilgtermiņā, un jūs, iespējams, nekad to nožēlosit!
Ja jums ir ieteikumi par skaidrāku kodu komentēšanu, lūdzu, informējiet mūs tālāk norādītajā diskusiju zonā!
