Učebnice PHP: Coding standards

Zkusím shrnout současné otázky k vyřešení a připojím pár nových. Ke každé otázce rovnou připojuji možné řešení, moje preferovaná varianta je vždy první. Pokud vám nabídka možností nebude stačit, vymyslete si vlastní a já (nebo spíš nějaký moderátor, vzhledem k tomu, že moje možnosti editace jsou časově omezené) ji sem doplním.

1) Umístění otevírací složené závorky u funkcí, metod, tříd, if, else, elseif, foreach, for, while, do, try, catch
    a) na nový řádek u funkcí, metod a tříd, všude jinde na stejný řádek
    b) všude na nový řádek
    c) všude na stejný řádek
2) Psaní mezery za if, else, elseif, foreach, for, while, do, try, catch
    a) mezeru psát, tj. if (...) { resp. if (...) (závisí na bodu 1)
    b) mezeru nepsat, tj. if(...)
3) Odsazování (z pohledu toho, co uvidí uživatel)
    a) 4 mezery
    b) 2 mezery
4) Psaní mezer okolo operátorů
    a) ano, např. $num > 10
    b) ne, např. $num>10
5) Psaní jednoduchých nebo dvojitých uvozovek u řetězců
    a) psát tam kde je to možné vždy jednoduché uvozovky, např. $s = 'Hello World!'
    b) psát všude dvojité uvozovky (kromě nějakých výjimek), např. $s = "Hello World!"
6) Porovnávání pomocí == nebo pomocí ===
    a) Preferovat ===
    b) Preferovat ==


Takhle se k tomu staví mnou zkoumané projekty:

1a: ZF, SF
1b: CI, Laravel
1c: Cake, PHPMailer, FB

2a: ZF, FB, PHPMailer, Laravel, Cake, CI, SF

3a: ZF, PHPMailer, Laravel, Cake, CI, SF
3b: FB

4a: ZF, FB, PHPMailer, Laravel, Cake, SF
4ab: CI

5a: FB, Laravel, Cake, CI, SF
5ab: PHPMailer, ZF

6a: Cake, CI, SF
6ab: Laravel, PHPMailer, FB, ZF

Jan Tvrdík:
z pohledu uživatele/programátora bych s tebou souhlasil snad ve všech bodech (nějak takhle taky píšu), snad jen v bodu 1) bych buď psal závorky vždy na stejný/nový řádek, ne jen někdy. Osobně preferuji vždy stejný řádek. Jinak bez problému, podle mě tvé možnosti „a“ jsou ustálené mezi většinou nepatlalů.

[#1] Jan Tvrdík:
Souhlasím se všemi body a).

Možná mi tam ještě chybí průzkum velkých/malých písmen a podtržítek u tříd/metod/funkcí/proměnných. Myslím ale, že převážná shoda bude v camelCase/CamelCase.

Keeehi:
„V takto krátkých ukázkách je to přehledné všechno, problém je, pokud se třeba po půlce stránky kódu vracíš o 3 úrovně. Při 2 mezerách se to hůře trefuje.“
Souhlasím.

Ugo:
„Ohledně verzí PHP bych to s těmi novinkami tolik nepřeháněl“
Tohle není projekt, který by měl udržovat kompatibilitu s muzejními verzemi PHP (5.2 a nižší).

„Interface bych pojmenovával s malým na začátku“
To je dost otřesné. Určitě ne.

„funkce již padlo že bez velkých počátečníc“
Určitě ano.

„proměnné jsou malými s podtržítkem“
Otřesné, rozhodně ne.

„Moc se mi nelíbí mezery za if, for atp. před závorkou“
Přidávají na přehlednosti.

Je přehlednější:
nebo:
Určitě 2. varianta.

Taurus:
„jen uvozovky určitě dvojité“
Ty bych používal jen pokud by usnadnily zápis, tj. např. proměnná v řetězci, nový řádek.

[#1] Souhlasím, jen v bodě 1 používám 1b a pak 3b, tím to ale neprosazuji.
Pokud budeme strojově obarvovat kód a jestliže v něm nebudou nějaké ručně dopsané formátovací značky, není problém to snadno přeformátovat, každý má IDE, které to umí.

Jan Tvrdík:
OK, bude určitě moudré vyjít z už definovaných pravidel nějakého velkého projektu.
Jak jsem psal, já nabyl dojem, že coding standards v PHP jsou stručně řečeno bordel, takže jsem částečně přebíral podle C#.
Tak trochu to závisí i na tom, jestli třeba o Nette chceme psát i v rámci učebnice. Kdyby ano, určitě by bylo jednodušší dodržovat rovnou jejich pravidla.

ad 1) Závorka na novém řádku mi přijde přehlednější, lépe se v tom bude orientovat. Takže b) nebo a)
Související téma, co ukončení IF za kterým následuje else?
nebo
nebo

ad 2) Asi lepší a), byť já osobně jsem zvyklý psát všechno stejným stylem jako volání funkce, včetně třeba if(něco) a echo(něco). Ale určitě to pomůže začátečníkům víc znázornit, že to funkce nejsou.
ad 3) Nevidím problém ani s jedním. Já osobně mám radši tabulátory spíš užší než širší, protože při určování rozsahu dlouhého bloku se stejně radši spolehnu na IDE (obarvení bloku nebo zvýraznění závorek) a široké tabulátory na vyšších úrovních zanoření zabírají hrozně místa, hlavně když je zároveň daný počet znaků na řádek. Ale nepředpokládám, že v příkladech v učebnici by se takové úrovně zanoření často vyskytovaly.

Když už jsem to nakousl: Bude se nějak omezovat počet znaků na řádek? Pokud ano, obvyklý limit 80 znaků na řádek mi přijde při dnešních monitorech nesmyslný. Nevidím důvod mít řádky zalámané na úzký proužek kódu a kolem mít spoustu prázdného místa. Takže pokud už budeme dávat nějaký limit, alespoň tak 120 (mimochodem, tady na diskusi se kód šířky 120 pořád vejde při zobrazení v rozlišení šířky 1280 v Opeře se zapnutým postranním panelem).

ad 4) Jsem pro mezery, určitě.
ad 5) a 6) Je potřeba tohle vůbec regulovat? Zejména uvozovky bych, pokud jsou v daném případě obě varianty ekvivalentní, nechal na volbě autora.
Spíš se nabízí otázka, jestli v příkladech používat i heredoc a nowdoc syntaxi (samozřejmě krom výkladu té syntaxe).
Možná by bylo dokonce fajn ji (v pokročilejší části) v několika příkladech použít záměrně (s vysvětlivkou/odkazem), aby si na ni čtenáři zvykli.

Joker:
„co ukončení IF za kterým následuje else?“
varianta (a) a (c) předpokládá

varianta (b) předpokládá

„Bude se nějak omezovat počet znaků na řádek?“
Celý řádek se musí zobrazit bez nutnosti scrollovat. Žádné další omezení nedává smysl.

„Zejména uvozovky bych, pokud jsou v daném případě obě varianty ekvivalentní, nechal na volbě autora“
Jsem velký nepřítel nekonzistence a odmítám argument o hypotetické rychlosti jednoduchým uvozovek (všechny testy, které jsem četl, potvrzují, že rychlostně je to zcela srovnatelné).

Jedna z možností, jak otázku (5) vyřešit, je používat apostrofy u konstantních řetězců (typicky hodnoty konstant, klíče asociativních polí apod.) a uvozovky u „uživatelských textů“ (obvykle věty nebo to, co vidí uživatel) jako třeba výpis textu pomocí echo nebo text výjimek (a to i v případě, že neobsahují proměnnou).

„jestli v příkladech používat i heredoc a nowdoc syntaxi“
Vzhledem k tomu, že ta syntaxe je téměř na nic, tak asi ne. Pokud se náhodou vyskytne příklad, kde by se hodila (o čemž pochybuji), tak se samozřejmě jejímu použití nebráním.

Revize návrhu ve smyslu toho, na čem zdá se panuje shoda:

• Ukázkový kód by neměl obsahovat syntaktické chyby, jeho zkopírování a spuštění by nemělo končit parse error. Kód nevhodný pro kopírování (např. demonstrující špatné návyky, neúplný apod.) může obsahovat záměrné syntaktické chyby jako prevenci proti bezmyšlenkovitému kopírování. Článek na to ale musí upozornit.
• Třídy a rozhraní se pojmenovávají v PascalCase (Upper CamelCase), rozhraní s „I“ na začátku jména (NejakaMojeTrida, IRozhrani)
• Funkce, proměnné a vlastnosti tříd se pojmenovávají v (lower) camelCase ($nejakaPromenna, function nazevFunkce, Kruh::spocitejObvod)
• Každý příkaz se píše na nový řádek.
• Ve výrazech se kolem operátorů píší mezery ($y = ($x + 1) / 2;)
• U řídicích struktur se preferuje syntaxe se složenými závorkami před syntaxí s dvojtečkou ( if (podmínka) { kód } před if (podmínka): kód; endif;), podmínka je uzavřena do závorek, před kterými se dělá mezera.
• Bloky kódu se odsazují dvěma 4 mezerami, složené závorky se píší na zvláštní řádek*bude doplněno* a uvádějí se i v případech, kdy nejsou povinné.
• Výhýbáme se zhuštěným špatně čitelným konstrukcím, případně konstrukcím spoléhajícím na vlastnosti jazyka, které nejsou zřejmé a v článku nejsou vysvětlené
• Pokud kód používá proměnné jinak než čistě demonstračně (kdy daná proměnná je v kódu jen kvůli syntaktické správnosti a úplnosti), mají proměnná název vystihující jejich smysl, který má zároveň rozumnou délku, tedy nesprávné názvy jsou třeba $d, $promennaKamSeUloziDelkaTextuVPolicku, správně může být třeba $delkaTextu.
• V rámci základního kurzu lze od čtenáře očekávat znalost témat, která jsou v základním kurzu dříve než dané téma. Mimo základní kurz lze od čtenáře očekávat znalost základního kurzu a pokud dané téma má několik částí, předchozích částí tématu. Jiné požadované znalosti by měly být uvedeny.
• Kód by měl být přiměřeně okomentovaný, přičemž komentáře se píší česky a s diakritikou. Přiměřeně okomentovaný znamená, že budou vysvětleny nové věci. Dlouhý kód bez komentářů je špatně, rozepisovat každý krok kódu včetně triviálních konstrukcí které už čtenář má dávno znát je také špatně.
• Přednost mají inline komentáře (//komentář), umístěné buď za příkazem který vysvětlují na stejném řádku, nebo před kódem který vysvětlují na samostatném řádku. Rozsáhlé obecné povídání o kódu patří do článku a ne do komentářů.
• Ukázky by se měly omezit na kód nutný k výkladu problému. Lze uvést jen část kódu a v článku zmínit, co se předpokládá že udělá neuvedený kód.
• Na druhou stranu by v příkladech měly být bezpečnostní mechanismy jako ošetření vstupů, pokud je to pro výklad problému únosné. Pokud to únosné není, měl by příklad začínat až po načtení vstupů a v článku být uvedeno, že se předpokládá, že se o to postaral předchozí kód.

Taky preferuju dvě mezery... 4 mi přijdou už moc rozhnaple
Interface určitě s velkym I
A spíš bych se přiklonil k anglickým kódům... Přece jenom je to jakýsi nepsaný standard a začínající programátory to dožene k lepším návykům.
(a osobně když vidím $obraz->getSirka(); tak mam chuť vyskočit z okna)

ještě bych doplnil skládání řetězců, u vás to snad nehrozí, ale často vídám toto (nebo to samé mimo výpis, ale to vyvolá notice takže je zavrhnuto už)
stejně tak oddělovat výpis přes třídu (to teda ani nevim zda to funguje bez závorek (tušim že jo) :-P jednoduše mě nenapadne to zkusit)

kdyby se vyskytlo $this->$funkce() , tak zda psát $this->{$funkce}(). Na jednom pohovoru mi bylo opovržlivě vnuceno že dolar za šipkou být nemůže, nepotvrdilo se to teda, ale mám z toho od tý doby takový špatný pocit :D

co se týká komentářů, určitě bych alespoň u zmnce o jejich typech uvedl nevýhody inline komentářů, pár lidem ftp klient při uploadu vyhodil odřádkování (takže celej kód zakomentovanej) a to samé když je touha lehko zminimalizovat kód, tak překáží více

když tak všechno mezerovat, tak co se závorkami, teď co dělám s three.js tak se všude setkávám s funkce ( x + ( y - 5 ) ) .. což je teda hroznej paskvil (když to má třeba 5 zanoření) podle mě, ale ... podle mě ;)

Ugo:
„u vás to snad nehrozí, ale často vídám toto“
Na to nevidím nic špatného. Přehlížím něco?
Tvé pocity z pohovorů nás nezajímají, umíme věci napsat tak, aby fungovali, tvá nevýhoda inline komentářů je irelevantní a mezery na vnitřní stranu závorek snad nikdo psát neplánuje.

snake.aas:
„A spíš bych se přiklonil k anglickým kódům...“
Jako někdo z cílové skupiny si dovolím nesouhlasit. Začátečník mívá potíže rozlišovat řetězce, které jsou neměnnou součástí jazyka, od řetězců, které může či má měnit či vymýšlet on. V tomto má neanglický začátečník u vhodně napsaného návodu výhodu oproti anglicky mluvícímu a bylo by moudré toho využít.

Myslím, že by bylo vhodné při stanovování konvencí myslet na to, že pro požadovaný formát by měla být funkce pro automatickou korekci.

Doufám, že tu nikoho nenapadlo si ručně počítat kde má být kolik mezer atd.

Str4wberry:
Předpokládám, že podobně jako tato diskuse by editor článků uměl vložit na tabulátor daný počet mezer.
Ale najít uvnitř kódu řádky které na začátku mají počet mezer nedělitelný 4 by taky nemělo být těžké.

K tomu formátování... Já dělám v NetBeans a tam je výchozí automatické formátování nastaveno jako v [#9] od Jokera a závorky u podmínek jako v prvním příkladu z [#8] od Jana Tvrdíka. Nevím, jak je to v ostatních IDE, ale asi to bude podobné. Myslím, že by bylo vhodné jedno IDE vybrat, pravidla formátování od něj převzít a doporučit ho na začátku učebnice (to IDE). Čtenáři by pak měli stejné formátování jako v učebnici.

Dovolím si pár svých skromných názorů :)
- odsazení hlasuji pro 4 mezery, cokoliv ostatního nemůžu ani vidět :) a mezery nikoli taby, s těmi jsou jen problémy.
- jazyk - jsem pro češtinu maximálně v komentářích, a to ze dvou důvodů:
- Stojím si za názorem, že slušný programátor by měl psát kód anglicky - komentáře přeložit není problém, ale překládat identifikátory,když se programátor rozhodne kód ukázat někomu, kdo česky neumí, je obzvláště v PHP špatný nápad.
- Pokud to někdo s programováním myslí vážně do té míry, že si o něm něco začne číst, počítačová angličtina je pro něj nezbytná - přeložit si v online slovníku základní programátorskou angličtinu zvládne každý a identifikátory v programu jsou většinou jednoduchá slova, která takto překládat jde (já kolikrát sahnu po slovníku, když pojmenovávám proměnnou).

Jan Tvrdík:
„Nicméně trochu tápu, jestli vlastní kód psát česky nebo anglicky. Český kód vypadá divně (protože se nevyhnutelně míchá s anglicky pojmenovanými vestavěnými funkcemi)“
A názov tohoto vlákna? To sa to nikomu nezdá divné? Neexistuje snáď český ekvivalent „Coding standards“? Nemalo by sa viac dbať na to, aby taký mix nebol v texte učebnice?

_es:
Toto vlákno jsem nezaložil a tedy ani nestanovil titulek. „Coding standards“ je programátorský termín. Je zcela běžné, že anglické termíny nemají český ekvivalent. Nebo ho mají, ale nikdo ho nepoužívá a tedy mu nikdo nerozumí. Použití anglických termínů se v učebnici rozhodně nevyhneme. Pokud má termín rozumný český ekvivalent, bude preferován.

Jan Tvrdík:
Někdy se používá český termín "firemní/štábní kultura", ale to většinou zahrnuje více než pouze coding standards.

Jan Tvrdík:
„Je zcela běžné, že anglické termíny nemají český ekvivalent.“

J. A. Komenský:
„Cokoli latinsky, cokoli německy, totéž stejně dobře i česky povědíno býti může...“

Věřím, že to platí i pro angličtinu. :-) Čeština je bohatý jazyk. Možná nelze všechno přeložit do výrazů českého původu, ale všechno lze přizpůsobit české gramatice.

Dobré zvyky při psaní kódu
Dohoda o psaní kódu
Dohoda o kódu
Formátování kódu
Optika kódu
Kódovací předpisy
Kódovací standard
Kódovací konvence
Kódovací kultura neboli "kódka" :)

Petr ZZZ:
„ale všechno lze přizpůsobit české gramatice.“
pak ale nebude na první pohled zřejmý význam, zatímco „coding standard“ je termín běžně užívaný a každý, kdo jednou bude chtít nastoupit na pozici programátora, se s ním musí setkat (bavíme-li se o seriózní společnosti).

Běžně taky užíváš FTP a ne český ekvivalent Protokol Přenosu Souborů.

Osobně bych tyhle anglické terminy-techniky z běžného programátorského života užíval i v učebnici, s tím, že při prvním výskytu termínu může být poznámka pod čarou s letmým vysvětlením.

Petr ZZZ:
„Dobré zvyky při psaní kódu“
Tohle mi připadá spíš bližší výrazu "best (coding) practice".
Spojení odvozená od "kódování" vnímám v češtině jako související s nějakým převodem (url-encoded, grafika do HTML), kdežto "kód" pro mne v kontextu počítačů znamená vždy "programový kód, zápis programovacím/skriptovacím jazykem". Ale možná pro lidi "od fochu" a s delší praxí už v tom není žádný rozdíl.

Co třeba "Jednotný styl kódu"?

_es, Petr ZZZ:
Termín coding standards samozřejmě má český překlad, normy pro psaní kódu, který nikdo nepoužívá a nikdo mu nerozumí.

V učebnici budou samozřejmě veškeré termíny vysvětlené, ale budou se používat ty, které se používají v praxi.
Nebudeme za každou cenu vymýšlet české překlady, kterým pak v praxi nebude nikdo rozumět.

Například teď dělám na druhé kapitole základního kurzu, kde je řeč o PHP IDE. Sice tam je napsané, že integrated development environment je česky integrované vývojové prostředí, ale jinak mám všude IDE.

Jinak diskuse ohledně pojmenování vlákna mi přijde zbytečná.

Reagoval jsem spíš obecně na Honzovo tvrzení, že něco anglického by snad (ještě k tomu zcela běžně) nešlo říct česky. Jak čemu říkat v tutoriálu je samozřejmě v první řadě na autorech.

Joker:
„Termín coding standards samozřejmě má český překlad, normy pro psaní kódu, který nikdo nepoužívá a nikdo mu nerozumí.“
Nezdá sa mi to ako správny preklad - z viacerých dôvodov.

„Sice tam je napsané, že integrated development environment je česky integrované vývojové prostředí, ale jinak mám všude IDE.“
Zaužívané anglické skratky sú niečo iné. Niektoré sa už používajú aj ako spisovné české slová - napríklad laser.

„Nebudeme za každou cenu vymýšlet české překlady, kterým pak v praxi nebude nikdo rozumět.“
Keď bude v prvých častiach učebnice vysvetlené, čo je ktorými pojmami myslené, tak to snáď nebude taký problém. Ak má byť učebnica pre začiatočníkov, tak by bolo asi lepšie preložiť čo najviac do češtiny - aby čitateľa málo účelný nadmerný počet anglických slov „nevyplašil“. Trochu mi to pripadá ako keď sú vo webových stránkach v menu zmixované české a anglické názvy odkazov.

Lamicz:
„Někdy se používá český termín "firemní/štábní kultura", ale to většinou zahrnuje více než pouze coding standards.“
Čo viac? Takýto pojem sa vyskytuje aj v tlačenej literatúre.

_es:
„Ak má byť učebnica pre začiatočníkov, tak by bolo asi lepšie preložiť čo najviac do češtiny“
Podle mě je pro začátečníky vhodné používat termíny, které se používají v praxi.
Bystřejší začátečníci budou hledat anebo číst i další zdroje kromě té učebnice a budou se divit, proč nic nenacházejí a budou zmatení, že jiné zdroje používají úplně jinou terminologii.
Příklad toho, jak by to podle mě mělo být: Cookies"> Cookies
Na začátku je zmíněno, že cookie lze přeložit jako sušenka či koláček, ale jinak se používá obecně známý anglický termín. Navíc v tomhle konkrétním případě je překlad nicneříkající a zbytečný. A ještě k tomu jen fakt, že angličtina používá jedno slovo ve dvou významech, neznamená, že i čeština musí mít pro oba významy jedno slovo. Takže český překlad počítačových cookies nemusí být vůbec závislý na českém překladu potravinářských cookies. Klidně by se jim mohlo říkat třeba lístečky (jako papírky s poznámkami), nebo jinak. Může to být i úplně nové slovo, takže podle mě by překlad mohl být i kukiny nebo kůkís.

Joker:
„používat termíny, které se používají v praxi.“
Nezdá sa mi, že by sa v odbornej českej (tlačenej) literatúre používal tento anglický výraz v mixe s bežným českým textom. V akých knihách to je tak použité? A ako sa to tam skloňuje? Iné termíny sa používajú, napríklad vo viacerých českých knihách je použitý termín „štábní kultura“.

„Příklad toho, jak by to podle mě mělo být: Cookies"> Cookies“
Toto je príklad odborného názvu pochádzajúceho z iného jazyka, pre ktorý neexistuje zaužívaný český ekvivalent, čo sa o „coding standards“ tvrdiť nedá.

_es:
Znovu: Coding standards není v té učebnici, ale titulek vlákna na diskusi.
Řešit konkrétní termíny použité v tomhle vlákně je zbytečné.
Terminologii použitou v rámci učebnice smysl řešit má, ale svou představu jsem snad už nějak popsal.

Nicméně se přiznám, že jsem v praxi nikdy neviděl použití českého ekvivalentu k coding standards.
Kdybych to měl použít v té učebnici, nějak bych to česky opsal (asi Pravidla pro psaní kódu, Doporučení pro psaní kódu) a pak řekl, že běžně se používá termín coding standards.
Termín firemní/štábní kultura vzhledem k coding standards rozhodně nevnímám jako ekvivalent, ale jako nadmnožinu, neboli firemní kultura = coding standards plus další věci (například pravidla pro práci s CVS, komunikaci v týmu nebo třeba tisk papírových dokumentů).

Reaguji na Jokera:
[cookie] „Může to být i úplně nové slovo...“
Ano.

„...takže podle mě by překlad mohl být i kukiny nebo kůkís.“
Z kůkís se mi ježí chlupy; měkké i po k je proti pravopisu, celý ten tvar proti gramatice (nejde pořádně skloňovat) a nenapadá mě české podstatné jméno se dvěma dlouhými slabikami bezprostředně po sobě.

První varianta se mi líbí, jen bych v zájmu stability pravidel pravopisu psal buď kukyna s tvrdým y po k, nebo kučina s č před měkkým i. Podobné slovo – bučina – už čeština zná, takže by šlo už jen o to, si na kučinu zvyknout.

Kučina, bez kučiny, kučině, kučinu, kučino!, o kučině, s kučinou.
Kučiny, bez kučin, kučinám, kučiny, kučiny!, o kučinách, s kučinami.

Mně by se líbilo cookie = kučina. :-)

„Termín firemní/štábní kultura vzhledem k coding standards rozhodně nevnímám jako ekvivalent“
Co kodérská kultura?