Učebnice PHP: Coding standards

Vznikly následující 4 vlákna a trochu teď tápu, co kam psát, tak mě když tak přesuňte.

1. Nový web o PHP – shrnutí diskuse o obsahu
2. Učebnice PHP: Tvorba obsahu
3. Učebnice PHP: Redakční systém
4. Učebnice PHP: Licence


Ohledně coding standards:
Nechybuji o tom, že veškeré komentáře v kódu budou česky. 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), ale předpokládám, že naše cílová skupina česky psaný kód ocení. Co si o tom myslíte? Co takhle alespoň část o OOP psát anglicky? Nebo můžeme zkusit anglicky psát všechno a hlídat si, že budeme používat jednoduchou angličtinu.

Z nějakého důvodu mi blbne editace v Opeře. Nadává na chybějící referrer, přestože jeho posílání mám explicitně povolené.

„Český kód […] se nevyhnutelně míchá s anglicky pojmenovanými vestavěnými funkcemi“

Což je při výuce spíš ku prospěchu. Mám názor, že by česky mělo být vše, co jen půjde.

Jan Tvrdík:
Jé, vlákno č. 1 mi nějak uniklo. Ta tři svoje jsem rozdělil podle oblastí, které se tu řešily. Coding standard by patřil do tvorby obsahu, ale možná když to vlákno č. 1 je shrnutí, mohli bychom tam dávat tyhle věci, až se na tom dohodneme. Konečnou licenci, doporučení pro autory, a tak podobně.

„Nicméně trochu tápu, jestli vlastní kód psát česky nebo anglicky.“
Věčné dilema :)
Ale minimálně v základním kurzu bych pojmenovával určitě česky. Jednak to bude začátečníkům srozumitelnější a jednak se víc odliší vestavěná funkčnost a uživatelsky definovaná.

Joker:
„ale možná když to vlákno č. 1 je shrnutí, mohli bychom tam dávat tyhle věci, až se na tom dohodneme. Konečnou licenci, doporučení pro autory, a tak podobně.“
Ano, původně to byla diskuse. Pak jsi založil svou, tak jsem to přejmenoval. Budu tam dávat shrnutí.

Základní kurz by mohl být česky. Dál jsem pro angličtinu.

Taurus:
„Pokud to ale budete mít obarvené“
To je taky kapitola sama o sobě. V zásadě existují tři možnosti.

1) Neobarvovat kód vůbec, to rovnou zavrhuji jako blbost.
2) Obarvovat kód strojově (ať už na serveru pomocí fshl nebo v prohlížeči pomocí jush)
3) Obarvovat kód ručně, tj. tak, jak to dělá Yuhů na jpw. Osobně si pamatuji, že mi to kdysi hodně pomohlo při učení html, protože bylo jasné, co spolu souvisí.

Varianta (3) by se navíc dala pomocí JS přepínat s variantou (2), což mi přijde nejzajímavější, přičemž (3) by byl výchozí stav.


Joker:
„jednak se víc odliší vestavěná funkčnost a uživatelsky definovaná“
Pamatuji, že to mi kdysi dávno při učení PHP pomohlo, takže v „Základním kurzu“ jsem spíš pro češtinu, stejně tak jsem spíš pro angličtinu v části o OOP. U těch ostatních částí jsem asi taky spíš pro češtinu, ale míň spíš než u té základní.

Jazyk je vždycky problém. I když mám češtinu rád, do programování ji moc necpu. Obzvlášť problémy jsou s diakritikou kdy pak v kódu vznikají zápalky či alkoholické nápoje, v případě slováků nadržené panely. Proto bych češtinu viděl nejraději jen v základním kurzu.

Související debata ohledně češtiny: Reakce chlupů na hlavě na diakritiku ve zdrojácích
Udělat přepínač, aby si sám čtenář vybral, jestli chce identifikátory česky či anglicky, by asi bylo zbytečně pracné, že? :-)

Chamurappi:
přepnutí jazyku - práce na 20 minut včetně administrace

Ugo:
„přepnutí jazyku - práce na 20 minut včetně administrace“
A to jsi si vycucal zase z jakého prstu?

Chamurappi:
„Udělat přepínač, aby si sám čtenář vybral, jestli chce identifikátory česky či anglicky, by asi bylo zbytečně pracné, že?“
Autor by musel vždy vymýšlet 2 názvy. Dobře dejme tomu, ale podle mě je problém, že tyto identifikátory nejsou jen v částech kódu. Co s těmi, které by byly zmíněné v textu? Ty by měly být také přeloženy. Co když ale to slovo k nahrazení jednou je a jednou není identifikátor?

Keeehi:
„Co když ale to slovo k nahrazení jednou je a jednou není identifikátor?“
Identifikátory by se museli obalovat nějakým tagem. Do první verze se to ale určitě nedostane, takže je zbytečné to rozebírat.

Koukám příspěvky se přesunuly do nových vláken, ještě k předchozímu:
Marek88:
„Podle mě pro úplný začátek OOP je nejnázornější geometrie.“
Geometrie má zase svoje problémy. Na druhou stranu by bylo fajn tam tohle (problém „kruh není elipsa“) zmínit.

Jinak se zdá, že pro základní kurz většina preferuje češtinu. Jen dodám, že já myslel bez diakritiky, nějak mi vůbec nepřišlo na mysl používat v názvech diakritiku.
V OOP čeština vypadá trochu divně vzhledem k tomu, že se pro čtecí a nastavovací metody se používají prefixy „get“ a „set“, takže pak vznikají věci typu „GetPocet“, „SetJmeno“ a podobně.

Nejsem si ale jistý, jestli v každé sekci používat jiný způsob pojmenování.
Další pravidla navrhuji:
• 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.
• Funkce a proměnné budou pojmenované v lower CamelCase ($nejakaPromenna, function nazevFunkce)
• Třídy, rozhraní a jejich vlastnosti budou pojmenované v upper CamelCase (Kruh::Polomer, Kruh::SpocitejObvod())
• Rozhraní budou pojmenovaná s „I“ na začátku, u jiných tříd se budeme vyhýbat názvům začínajícím na I.
• Každý příkaz se bude psát na nový řádek.
• 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;)
• Bloky kódu se odsazují dvěma mezerami*, složené závorky se píší na zvláštní řádek 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ě.
• 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.

* To bychom mohli změnit podle konečné podoby redakčního systému.

[#3] Str4wberry:
„Což je při výuce spíš ku prospěchu.“
Přesně tak. Prosím o češtinu všude, kde nemusí být angličtina.

Joker:
„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.“
Za důležité považuji předem jasně určit, jaká verze PHP je cílová pro příklady. Osobně si myslím, že v tuhle chvíli je to 5.3. Vyžadoval bych proto kompatibilitu všech kousků kódu s PHP >=5.3.0.
Zároveň považuji za naprosto nepřijatelný jakýkoliv kus kódu, který by implicitně (při zamýšleném chování, nikoliv při chybovém stavu) produkoval chybové hlášky (E_NOTICE včetně), pokud to není jeho demostrativní záměr.

„Bloky kódu se odsazují dvěma mezerami*“
S tímto budu poměrně zásadně nesouhlasit. Odsazování dvěmi mezerami působí nedostatečně a nepřehledně, navrhuji čtyři. Zároveň bych v ideálním případě místo mezer preferoval tabulátory o velikosti čtyř mezer.

„složené závorky se píší na zvláštní řádek a uvádějí se i v případech, kdy nejsou povinné“
Složené závorky na zvláštním řádku jsou rarita. Běžně se píší na stejném řádku. Platí pro if, for, foreach, while, switch apod.

„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.“
Zde bych volil takovou cestu, kdy by článek obsahoval informaci o tom, které jiné články je předem třeba znát. S tím, že tahle informace by byla jednotně prezentovaná (tj. ne součást článku samotného, ale jako metadata článku a následně vykreslována automaticky).

„Kód by měl být přiměřeně okomentovaný, přičemž komentáře se píší česky a s diakritikou.“
Ke komentování bych vyžadoval // s mezerou za před samotným komentářem. Co s víceřádkovými komentáři? /* ... */ na mě působí poněkud nepřehledně.

„Na druhou stranu by v příkladech měly být bezpečnostní mechanismy jako ošetření vstupů“
To považuji za kritické. Vlastně bych to považoval za klíčový bod každého článku, včetně základního kurzu. Pokud by tam bezpečnostní mechanismy nebyly, povede to ke špatným návykům učícího se.

Joker:
„mají proměnná název vystihující jejich smysl“
„Kód by měl být přiměřeně okomentovaný“ ... apod.
Mělo by smysl mít samostatný článek o coding standards, anebo to chcete nechat jen jako pravidlo pro autory článků?

Joker:
„Nejsem si ale jistý, jestli v každé sekci používat jiný způsob pojmenování.“
Co myslíš jiným způsobem pojmenování?

„Další pravidla navrhuji:“
Jak už jsem psal, tak se přikláním přibližně k Nette Coding Standards. Nicméně zkusil jsem provést průzkum na následujících významných PHP projektech: ZF, FB, PHPMailer, Laravel, Cake, CI a SF.

„vlastnosti budou pojmenované v upper CamelCase“
Pojmenovávat všechny metody a vlastnosti „upper CamelCase“ (dále jen ucc) je silně netypické. Pojmenovávat pouze veřejné metody a vlastnosti UCC je běžné třeba v C#. V PHP je ale výrazně převládá použití „lower CamelCase“ (dále jen lcc) i pro public metody a vlastnosti.
Z uvedených projektů pouze PHPMailer používá UCC pro veřejné metody a vlastnosti.

„u jiných tříd se budeme vyhýbat názvům začínajícím na I“
To je nesmysl. Proč by se třída nemohla jmenovat třeba Image?

„U řídicích struktur se preferuje syntaxe se složenými závorkami před syntaxí s dvojtečkou“
V praxi se pokud vím ta alternativní syntaxe (if: ... endif;) používá akorát v šablonách.

„složené závorky se píší na zvláštní řádek“
Osobně se domnívám, že psaní otevírací závorky na samostatný řádek je lepší pro větší projekty (proto tuto variantu používáme ve firmě) a psaní otevírací závorky na stejný řádek s if, else… je lepší pro menší projekty. Vzhledem k rozsahu příkladů mi tedy přijde lepší psaní otevírací závorky na stejný řádek.

„uvádějí se i v případech, kdy nejsou povinné“
S tím také nesouhlasím, ve spoustě situací je inline zápis imho přehlednější.

„if($pocet > 1)“
Za if, else, foreach, while… by měla být jedna mezera. Shodují se na tom všechny výše uvedené projekty. Stejně tak by měly být mezery okolo operátorů.

Majkl578:
„Za důležité považuji předem jasně určit, jaká verze PHP je cílová pro příklady. Osobně si myslím, že v tuhle chvíli je to 5.3. Vyžadoval bych proto kompatibilitu všech kousků kódu s PHP >=5.3.0.“
Jo, to je rozumné.
Taky by bylo dobré přidat pravidlo, že pokud kód závisí na jiném nastavení serveru než je výchozí nastavení té verze, mělo by to být v článku napsané.

„Zároveň považuji za naprosto nepřijatelný jakýkoliv kus kódu, který by implicitně (při zamýšleném chování, nikoliv při chybovém stavu) produkoval chybové hlášky (E_NOTICE včetně), pokud to není jeho demostrativní záměr.“
Bral jsem ohled na to, že některé příklady nemusejí být celé, ale může být jen slovně popsané, co by dělal předchozí kód. Takové příklady by při zkopírování a vložení různé hlášky generovat mohly, ale ne parse error.

> „Bloky kódu se odsazují dvěma mezerami*“
> S tímto budu poměrně zásadně nesouhlasit. Odsazování dvěmi mezerami působí nedostatečně a nepřehledně, navrhuji čtyři. Zároveň bych v ideálním případě místo mezer preferoval tabulátory o velikosti čtyř mezer.
To se používá tady na diskusi a přišlo mi to OK.
Jelikož výstupem je HTML, s tabulátory bude asi problém.
Jinak souhlasím, že při psaní ostrého kódu v editoru se mají používat tabulátory.

> „Na druhou stranu by v příkladech měly být bezpečnostní mechanismy jako ošetření vstupů“
> To považuji za kritické. Vlastně bych to považoval za klíčový bod každého článku, včetně základního kurzu.
Na druhou stranu, pokud ošetřování vstupů zabere daleko víc místa než demonstrovaná funkčnost, netrval bych na tom.
Přijde mi OK do článku napsat něco jako Pokud ošetřené vstupy máme načtené v těch-a-těch proměnných, můžeme použít kód atd.

A jinak se přiznám, že hodně těch návyků jsem převzal z C#, protože v PHP je stručně řečeno bordel. Ani ukázkové příklady v manuálu nepoužívají jednotný coding standard.

Ještě bych přidal:
• Ukázkový kód by neměl používat funkce označené jako deprecated, nejsou-li právě tyto předmětem ukázky. V takovém případě by ale článek měl zdůraznit, že danou funkci není radno používat.

Joker:
„Jelikož výstupem je HTML, s tabulátory bude asi problém.“
pokud kódy budou v pre, případně elementu s white-space: pre, příp. pre-wrap, problém by to být neměl.

Jen prohlížeč používá pro tabulátor nejvíce asi 8 mezer (nebo minimálně Firefox tuším odsazuje 8 mezerovým tabulárem) - nevím, toto asi změnit nepůjde.

panther:
„problém by to být neměl“
Problém je to právě proto, že prohlížeče to zobrazí jako 8 mezer, což učiní kód špatně čitelným. Změnit to lze pomocí CSS 3 vlastnosti tab-size, která má však velmi bídnou podporu.

Joker:
„Ukázkový kód by neměl používat funkce označené jako deprecated“
Určitě, zapomněl jsem to zmínit.

To znamená vše, co:
a) již vyhazuje E_DEPRECATED (ereg atd.),
b) v PHP 5.4 (resp. novějších verzích než 5.3) nefunguje (session_register atd.),
c) je nedoporučováno (zejména všechny funkce mysql_*),
d) má nejistou budoucnost (např. přístup k řetězcům přes {}: $x{1}).

Zároveň bych ale byl pro dopřednou kompatibilitu. Tzn. všude, kde to možné je, zmiňoval i věci, které fungují až od 5.4 (array dereferencing, krátký zápis polí atd.) s tím, že by tam byla poznámka, že to funguje až od verze 5.4.

Spekulativní pak je, jestli zmiňovat věci, které jsou do budoucna plánované (5.5), ale ještě nejsou součástí stabilní verze (např. podpora isset/empty na výsledky funkcí a výrazy, aktuálně v plánu do 5.5).

Majkl578:
„s tím, že by tam byla poznámka, že to funguje až od verze 5.4.“
K tomuhle mě napadlo už dřív: bylo by případně možné si v uživ.profilu nastavit, jakou verzi PHP používám/preferuji, s tím pokud mám nastavené 5.4, tak se mi např. nezobrazí tahle poznámka u krátkého zápisu polí? Anebo je lepší to uvádět všude, aby i člověk, kterého se to přímo netýká, získal přehled?

Tori:
Líbí se mi, jak ještě nemáme žádný redakční systém a už vymýšlíte spoustu složitostí na něm závislých :)
Osobně si myslím, že by bylo škoda uživatelům PHP 5.3 tajit, že v PHP 5.4 se něco bude dělat jinak.

„bylo by případně možné si v uživ.profilu nastavit, jakou verzi PHP používám/preferuji“
Většina čtenářů pravděpodobně nebude mít žádný uživatelský profil.

„Anebo je lepší to uvádět všude, aby i člověk, kterého se to přímo netýká, získal přehled?“
Přesně to si myslím.

Jan Tvrdík:
„Problém je to právě proto, že prohlížeče to zobrazí jako 8 mezer“
jo takhle je to myšleno. To mě mělo také napadnout, že Joker bude vědět, jak zobrazit odsazený kód...

O této vlastnosti jsem, přiznám se, dosud neslyšel.

Co takhle psát kód s tabulátory a při ukládání nahrazovat za sadu 4 mezer (a při editaci zpět na tabuláry)? Uživatel si zkopíruje čtyři mezery.

Majkl578:
„Spekulativní pak je, jestli zmiňovat věci, které jsou do budoucna plánované“
Tohle mi zrovna spekulativní nepřipadá, protože uvádět to považuji za nesmysl. Až PHP 5.5 vyjde, informace do článků doplníme.

panther:
„Co takhle psát kód s tabulátory a při ukládání nahrazovat za asu 4 meze“
To by šlo, funguje to tak na nette.org a problémy s tím nejsou. Má to akorát nevýhodu, že to bude vypadat hnusně (8 mezer se mi prostě nelíbí) v textarea (teda kromě těch pár prohlížečů, kde to asi půjde nastavit).

Tori:
„bylo by případně možné si v uživ.profilu nastavit, jakou verzi PHP používám/preferuji, s tím pokud mám nastavené 5.4, tak se mi např. nezobrazí tahle poznámka“
Zajímavý námět, ale jednak nevím, jestli nebude náročné vytvořit učebnici pro různé verze PHP, jednak různý obsah pro různé lidi může být zdrojem nedorozumění (jeden bude tvrdit že to na té stránce je a druhý zas že není) a jednak moc nevidím důvod takovou informaci nějak tajit ani před lidmi, kteří nemají správnou verzi PHP.

Ještě se vrátím:
Jan Tvrdík:
„Co myslíš jiným způsobem pojmenování?“
V jedné sekci česky, v jiné anglicky, atd.

„To je nesmysl. Proč by se třída nemohla jmenovat třeba Image?“
Hm, pravda.

„V praxi se pokud vím ta alternativní syntaxe (if: ... endif;) používá akorát v šablonách.“
Tazatelé tady v diskusi ji používají poměrně často.

„S tím také nesouhlasím, ve spoustě situací je inline zápis imho přehlednější.“
Já bych tu preferoval přehlednost.

edit, ještě k tabulátorům:
Neuděláme to tedy stejně jako diskuse (ta na tabulátor vloží dvě mezery)?

Joker:
„Neuděláme to tedy stejně jako diskuse (ta na tabulátor vloží dvě mezery)?“
Jak už jsem psal výše, dvě mezery se mi kvůli přehlednosti zdají málo a i zde odstazuji čtyřmi.

Majkl578:
„dvě mezery se mi kvůli přehlednosti zdají málo a i zde odstazuji čtyřmi“
souhlasím

Majkl578:
„dvě mezery se mi kvůli přehlednosti zdají málo a i zde odstazuji čtyřmi.“
Hmm, zkouška bez závorek na zvláštních řádcích:

Nevím, řekl bych, že i dvě mezery stačí.

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.

Keeehi:
prostě zkušenosti z praxe, zrovna minulej víkend sem si s jazyky hrál a tohle bych řešil stejně (prosté asociativní pole s funkcemi které už má asi každý vývojář hotové)

Můj názor na zde řečené:
Já mám třeba raději 2 mezery, ale asi jsem menšina :-P. Ohledně verzí PHP bych to s těmi novinkami tolik nepřeháněl, všes čím jsem za poslední 2 roky dělal (krom hostingů mnou vybraných, čili prostě v práci) běželo na PHP 5.2 (asi přes 300 webů)

Jednořádkový if (if() then;) bych si v učebnici dovolil možná v příkladu že to jde, závorky jsou jistota. Interface bych pojmenovával s malým na začátku iImage, iUser. Metody, funkce již padlo že bez velkých počátečních (getUser()) a za sebe mám kvůli menší možnosti překlepů a lepšímu odlišení rád když proměnné jsou malými s podtržítkem ($active_user). Moc se mi nelíbí mezery za if, for atp. před závorkou