Psaní kódu neboli programování je základní činností vývoje všech aplikací, které fungují na vašem počítači. Proto je dobrý kód nejdůležitější předpoklad dlouhodobě úspěšného projektu. Každý, kdo delší dobu programoval, se setkal se situací, kdy jeho práci významně zpomaloval zaneřáděný kód. Každá další změna kódu může způsobit nefunkčnost jiné části systému a tyto problémy je velmi obtížné dohledat a napravit. Časem se může stát, že míra nepořádku v kódu je tak značná, že to již nikdo nedokáže vyčistit a je lepší začít celý projekt úplně znovu. Tento problém je mnohem větší při práci v týmech a na rozsáhlejších projektech. Proto je velmi důležité psát kód hned od počátku tak, aby byl co nejčistější a v případě objevení jakéhokoli problému raději danou část přepsat do čistější podoby a udržovat tak kód stále čistý.
Proto máme u nás ve firmě sepsaná pravidla psaní kódu a každý je povinen tato pravidla dodržovat a kód neustále vylepšovat. O část těchto pravidel se s vámi chceme podělit a nechat vás nakouknout do způsobu práce našeho vývojového oddělení. Naše pravidla vycházejí z knížky s názvem Čistý kód jejímž autorem je Robert C. Martin a našich dlouhodobých zkušeností.
Formátování
- formátovací pravidla jsou povinná pro celý tým, protože programování není individuální činnost, ale týmová záležitost
- php kód vždy uvoďte sekvencí <!--?php a ukončete ?--> Na konci skriptu neuvádějte ukončovací sekvenci ?>
- odsazujte vždy o 4 mezery. Nikdy ne o tabelátor
- dodržujte správné odsazení, kdy celá vnořena úroveň je odsazena stejně a ukončovací složená závorka končí na stejné úrovni jako je kód mimo vnořenou úroveň
- dodržujte horizontální oddělení tj. mezery by měly být kolem všech operátorů jako je plus, mínus, rovnítko atd
- za klíčovým slovem např. if uvádějte mezeru
- počáteční složenou závorku umístěte v případě funkcí na nový řádek a v případě if, for atd. na konec řádku za mezeru
- složitější podmínky uveďte rozděleně na více řádků
- vždy rozepište příkazy if, for atd. na více řádků a vždy obsah těchto příkazů uzavřete do složených závorek
např.
if (isValid()) {
deleteCache();
}
místo
if (isValid()) deleteCache();
- komentáře vždy uveďte pomocí znaků // a v případě delších komentářů pomocí /* a */
- využívejte vertikální oddělování pojmů tj. mezi každými dvěmi pojmy, funkcemi atd. uveďte jeden prázdný řádek. Ten je “nápovědou”, že jde o novou myšlenku
- myšlenky, které spolu těsně souvisejí by měly být ve svislém směru blízko sebe
- jestliže jedna funkce volá druhou, měly by být vertikálně blízko sebe a volající funkce by měla být nad funkcí volanou
- horizontálnímu zarovnání se vyhněte, protože se při čtení automaticky zaměříte pouze na část řádků, ale důležitý je celý řádek jako celek
např.
private $synchronizator = false;
private $cache = false;
- nepoužívejte prázdné while atd.
ukázka formátování
- SQL příkazy pište tak, že všechna klíčová slova jsou napsána velkými písmeny a všechna ostatní malými
např.
SELECT FIRST 1 a.id, COUNT(b.sum) AS celkem FROM adresar a LEFT JOIN log b ON b.idcizi=a.id WHERE a.wp_typ=’ABC’ AND b.typ=’L’ ORDER BY a.id
Obecná pravidla
- dodržujte standardní konvence formátování viz výše
- vždy uvádějte viditelnost atributů a metod
- používejte konstanty se správným jménem místo tajemných čísel v kódu
- vždy ošetřete návratovou hodnotu funkce, aby nebyla null
- zapouzřete podmínky do funkce s jasným názvem místo nepřehledných logických příkazů
např.
if (shouldBeDeleted(timer))
místo
if (timer.hasExpired() && !timer.isRecurrent())
- vyhýbejte se negativním podmíněným výrazům, kterou jsou méně srozumitelné
např.
if (buffer.shouldCompact())
místo
if (!buffer.shouldNotCompact())
- funkce by měly vždy provádět pouze jednu věc jinak by měly být rozděleny
- výstup (HTML) nikdy negenerujte přímo ve funkcích. Vždy nejprve vygenerujte data a následně by měl mít objekt metodu pro generování HTML nejlépe pomocí XSL šablony a měl by tento HTML kod vracet jako řetězec a ne vypisovat přímo na výstup.
- vyhněte se psaní plošného kódu
Jména proměnných, funkcí, tříd
- používejte jména vysvětlující význam
- pro jména používejte anglický jazyk
- jména skládající se z více slov pište dohromady a každé slovo velkým písmenem např. elapsedTimeInDays
- výběr dobrých jmen zabere čas, ale mnohem více času ušetří
- změňte jméno, když přijdete na lepší
- jméno proměnné, funkce nebo třídy by mělo zodpovědět všechny zásadní otázky tj. proč existuje, co dělá a jak se používá. Pokud vyžaduje poznámku, pak svůj význam neodkrývá
- vyhněte se dezinformacím jako v názvu proměnné špatně uvedený typ např. accountList a přitom to není list atd.
- nepoužívejte jména, která se liší jen nepatrně např. v jednom písmenu
- podobné pojmy zapisujte podobným způsobem
- vynechte bezvýznamná slova
- tvořte jména tak, aby se dala vyslovit
- jména tříd mohou obsahovat podstatná jména nebo spojení podstatných jmen. V názvech by nemělo být sloveso
- jména metod by měla obsahovat slovesa nebo slovesné fráze např. deletePage, save. Pro přístupové metody použijte předponu get. Pro modifikátory použijte předponu set a pro zjišťování hodnot použijte předponu is.
- nepoužívejte vtipná pojmenování, slang, slovní hříčky
- volte jedno slovo pro jeden pojem např. nepoužívejte jednou fetch, jednou get a jindy retrieve. Nebo manager, controller.
- nebojte se vytvářet dlouhá jména. Dlouhé popisné jméno je lepší než jméno krátké a tajuplné nebo dlouhý komentář
např.
private elapsedTimeInDays;
private daysSinceCreation;
private fileAgeInDays;
místo
private d; // pocet dni
Funkce
- funkce by měly být malé. Vyjímečně by měly být delší než 20 řádků
- úroveň odsazení funkce by neměla být větši než jedna nebo dvě tj. místo zanořených podmínek atd. by se měla vytvořit další funkce
- každá funkce by měla dělat jen jednu věc, měla by ji dělat dobře a neměla by dělat nic jiného
- nikde neopakujte stejný kód, ale místo toho ho extrahujte do speciální funkce
- funkce by měla mít pouze jeden vstupní a jeden výstupní bod tj. jeden příkaz return
- nikde nepoužívejte příkaz goto
- ideální počet argumentů je nula, dále můžete použít jeden nebo dva argumenty. Třem argumentům se vyhněte a více než tři nepoužívejte
- raději nepoužívejte výstupní argumenty tj. předávané odkazem a jejich změny ve volané funkci.
- funkce by neměla mít žádné vedlejší efekty tj. např. funkce by neměly měnit argumenty třídy, globální proměnné atd, pokud k tomu není přímo určena tj. měla by dělat pouze jednu věc a neovlivňovat něco jiného
- funkce by měly buď něco dělat nebo na něco odpovídat, ale ne obojí
- dejte přednost vyjímkám před vracením chybových kódů
- extrahujte bloky try a catch do speciálních funkcí, protože směšují zpracování chyb s normálním během programu
např.
public void delete($page)
{
try {
deletePageAndAllReferences(page);
}
catch(exception $e) {
logError($e);
}
}
- první napsání programu, objektu nebo funkce je pouze první návrh a je potřeba ho restrukturalizovat dokud nebude kód čitelný. Je potřeba provést nahrazení jmen proměnných, rozložení do funkcí, pročištění atd.
Komentáře
- lepší než psaní komentářů je opravit a vyčistit kód
- pokud je potřeba napsat komentář, pak se jedná o špatný kód, který není srozumitelný
- pište základní komentář k hlavičce funkce
- pište komentář při použití nestandardního programovacího obratu
- občas je potřeba varovat v komentáři před důsledky jiného použití např. kvůli vytížení procesoru atd
- občas je vhodné napsat komentář todo
- nepište nadbytečné komentáře jejichž čtení zabere více času než pochopení kódu
- nepište nejasné komentáře
- nepoužívejte komentář, když můžete použít funkci nebo proměnnou nebo refaktorovat kód
- nepoužívejte komentáře označující pozici nebo oddělující části souboru
- nepoužívejte komentáře na konci složených závorek
- nepoužívejte zakomentované kusy kódu. Už nikdo nebude mít odvahu tyto kusy kódu smazat a zůstanou v kódu stále. Raději rovnou smazat a nechat původní verzi pouze ve správci verzí (svn)
Závěr
Možná i Vám se zdá tento článek a dodržování těchto pravidel zbytečné, ale na základě našich dlouhodobých zkušeností se jedná o jednu z nejdůležitějších zásad při vývoji aplikací. V současné době, kdy jsou internetové projekty čím dál složitější, se bez týmové práce moderní firma neobejde a pro práci v týmu musí být stanovena společná pravidla psaní kódu. O část pravidel našeho týmu jsme se s vámi chtěli podělit v tomto článku.
