Skôr než začne tím alebo programátor tvoriť projekt, je dôležité definovať pravidlá pre tvorbu kódu. Pravidlá sa musia týkať názvoslovia (naming conventions) a štýlu tvorby programového kódu (coding style). Pravidlá by mali byť spísané v dokumentoch a byť k dispozícii každému programátorovi z tímu. Dôležité je byť konzistentný a dohodnuté pravidlá neporušovať. Len tak sa docieli efektívny kód. Predstavené odporúčania v článkoch typu coding style a naming conventions nie sú zo žiadneho oficiálneho dokumentu, ale ide o súhrn pravidiel, ktoré som si v rámci praxe a študovania jazykov osvojil, a ktoré odporúčam. Množstvo pravidiel pochádza od lídrov komunity jazyka JavaScript, ako aj frameworkov Dojo, jQuery či NodeJS. Veľa odporúčaní mi často pripadalo vytvorených nasilu, len aby sa dáko odlíšili od ostatných. Stačí pozrieť zápis hlavičiek funkcií. Z tohto dôvodu som začal tvoriť návrh odporúčaní obsahujúci to "naj" z IT komunity, ktoré budem postupne predstavovať v jednotlivých článkoch.Príklad: Jedna z možností zápisu hlavičky funkcie.
1
2
3
4
5
// príklad coding style funkcie
function functionName ( parameter1, parameter2 )
{
code
}
Príklad: Moje odporúčanie bez bielych miest.
1
2
3
4
// moje odporúčanie coding style a naming convention funkcie
function functionName(parameter1, parameter2){
code
}
V tomto článku sa zameriavam na komentáre. Články typu coding style a naming conventions budú vychádzať z jazyka JavaScript, pričom množstvo tipov a odporúčaní je možné aplikovať aj v iných programovacích jazykoch.Každý programovací jazyk má vlastný štýl zápisu komentára, pričom niektoré programovacie jazyky ich majú rovnaké. Pre zápis komentára sa najčastejšie používajú znaky //, /* a */. Komentáre sa delia na jednoriadkové a viacriadkové. V tejto časti sa budem venovať správnemu odsadeniu komentárov.Pre sprehľadnenie programového kódu a zvýraznenie komentárov sa odporúča vytvoriť pravidlá pre odsadenie. Pravidlá pre odsadenie by sa mali najmä týkať počtu bielych miest a prázdnych riadkov. Pri jednoriadkových komentároch, ktoré začínajú zľava, by mal každý komentár predchádzať prázdny riadok. Odsadenie zľava by malo byť rovnaké ako má programový kód, ktorý za ním nasleduje.Príklad: Odporúčaný zápis komentára.
1
2
3
4
5
if(condition){
// comment
code
}
Pri zápise komentára do riadku za programový kód sa odporúča odsadenie od kódu o dve medzery.Príklad: Odporúčaný zápis komentára.
1
code;// comment
Príklad: Neodporúčaný zápis komentára.
1
code;// comment
Rovnako sa odporúča definovať odsadenie textu komentára od značiek komentára. Pre zbytočné plytvanie miestom a bajtami stačí jedna medzera.Príklad: Odsadenie textu od značiek komentára.
1
// stačí jedna medzera
Pri viacriadkovom komentári sa odporúča umiestňovať text tak, aby nebol na riadkoch so značkami komentára. Aj v tomto prípade sa odporúča odsadenie textu zľava o jednu medzeru.Príklad: Odporúčaný zápis komentára.
1
2
3
4
/*
Toto je viacriadkový komentár.
Tento obsah sa nikdy nespracuje.
*/
Príklad: Neodporúčané zápisy komentára.
1
2
3
4
5
6
7
/*
Toto je viacriadkový komentár.
Tento obsah sa nikdy nespracuje.
*/
/* Toto je viacriadkový komentár.
Tento obsah sa nikdy nespracuje. */
Pre sprehľadnenie a zároveň zvýraznenie viacriadkového komentára je možné použiť znak *. Aj pri tomto spôsobe zápisu je vhodné dbať na odsadenie znaku * a textu komentára. Odporúčané odsadenie je opäť jedna medzera.Príklad: Odporúčané zvýraznenie viacriadkového komentára.
Ako vidieť, aj komentáre majú svoj coding style. Dodržiavaním pravidiel pre písanie komentárov bude programový kód prehľadnejší, lepšie čitateľnejší a zároveň profesionálnejší.19.1.2013 (aktualizované 25.1.2013), Matej LednárKategória: ProgramovanieProgramovanie,programovanie,PHP,komentáre,JavaScript,coding style,naming conventions,good practices,bad practicesŽiadna časť tohto článku nesmie byť reprodukovaná bez uvedenia autora a URL na túto stránku.Viac informácií nájdete v sekcii O projekte.
