Učebnice PHP: Coding standards

_es, Petr ZZZ:
Pánové, přestaňte řešit blbost. Děkuji.

Když to tady čtu, tak si připadám jak v době národního obrození, kdy se Dobrovský, Jungmann a další snažili počeštit všechna slova. Jsem docela rád, že se jim to nepovedlo. Jsme raději student než knihovtipník, raději se dívám do kalendáře než do letodníkku a rozhodně jsem se učil hrát na piano a ne na klapkobřinkostroj. Nechte nám prosím naše coding standards a cookies. Jazyk se neustále vyvíjí, nová slova jsou přijímána a naopak stará zase vyřazována. Takže jednou, cookie může být klidně naprosto "legální české" slovo a nikdo se nad tím nebude vůbec pozastavovat. Ostatně slova jako třeba vesmír nebo pytel také nejsou původně z češtiny a dnes ani nikoho nenapadne to zkoumat.

Honzo, nic ve zlém, ale když už, tak mi ve srovnání s otázkou úrovně češtiny v české učebnici přijde zbytné řešit otázku, zda jsou v ukázce kódu lepší dvě nebo čtyři mezery. :-)

Nicméně přiznávám, že téma tohoto vlákna je kód. Možná by to chtělo separátní vlákno věnované otázkám jazyka učebnice. (Já ho zakládat nebudu. Měl by ho případně založit někdo, kdo bude moci editovat úvodní příspěvek v závislosti na vývoji diskuse; ten by měl shrnovat doporučení k použité terminologii. Časem by se z takového vlákna mohl vyklubat terminologický slovníček – který by se mimochodem velmi hodil.)

Keeehi:
„Jazyk se neustále vyvíjí...“
Což je svým způsobem – z dlouhodobého hlediska – tragédie. Kdyby se nevyvíjel, byli bychom schopni porozumět starým textům. Díky trvanlivosti písemného záznamu by mohl text sloužit i k přenosu informací na časové ose. Vývojem jazyka však dochází k jeho přeměně, která má za následek, že jazyk dokáže sloužit jako dorozumívací prostředek pouze současníkům nebo nanejvýš přes několik málo generací.

Petr ZZZ:
Kdyby se nevyvíjel, nemohli bychom si zase povídat o dnešku, protože bychom měli k dispozici jen ta slova ze starých textů. Vývoj je přirozený děj a v určitém okamžiku jazyk zmrazit, nic nového nepřijímat a nic neodstraňovat by podle mého názoru byla pohroma.

Petr ZZZ:
„Nicméně přiznávám, že téma tohoto vlákna je kód.“
Ano, to je ta důležitá věc.

„Možná by to chtělo separátní vlákno věnované otázkám jazyka učebnice.“
Zatím jsem necítil potřebu ho zakládat.
Možná je to i tím, že zatím je zveřejněná jen jedna kapitola, kterou jsem psal já. Možná až bude víc textů od více autorů, zjistíme, že je potřeba nějaká pravidla dohodnout.

Zatím ale nevím, o čem by se obecně diskutovalo. Spíš by to měly být konkrétní komentáře u zveřejněných textů, případně by se autor během psaní zeptal, jak má nějaký termín vyložit.

Ve vláknu o tvorbě obsahu už ostatně byly takové připomínky k první kapitole a přišlo mi to docela vyhovující.
Vznikl seznam připomínek, já je prošel, většinou text upravil, některé se staly irelevantními kvůli předchozím úpravám a pár připomínek jsem zavrhl, protože mi moje verze přišla lepší. Mám za to, že u připomínek, které jen navrhují „lepší formulaci“ jinak obsahově i pravopisně správného vyjádření, by mělo rozhodnutí o koneční podobě textu být na autorovi.
Samozřejmě problém by vznikl ve chvíli, kdy by v tom vlákně vznikaly několikastránkové debaty o jednom slově.
Ale tak počkejme jestli vzniknou a případně založme potom pro ně nové vlákno.

Dodatek, Petr ZZZ:
„Kdyby se nevyvíjel, byli bychom schopni porozumět starým textům.“
Kdyby se nevyvíjel, byl by mrtvý. Vývoj je život. Potíž je způsob, jakým se čeština vyvíjí, ale to tady nevyřešíme a připadá mi zbytečné o tom diskutovat.

Zajímalo by mě, zda se vám podaří učebnici dodělat navzdory vytrvalým snahám Petra ZZZ zamořit tvůrčí proces rozvleklými pojednáními o nepodstatných maličkostech. Je načase vyhlásit briefing o coding standards…

Snad jo. Zkusil jsem to briefly. :)

Ahoj,

zatím jsem se k učebnici PHP nevyjadřoval, ale když už jsme u těch cizích slov, tak by asi mohl být pod každou kapitolou odkaz na "terminologii", kde by byly tyto cizí termíny vysvětleny.
Každé cizí slovo by potom mohlo soužit jako odkaz na kotvu na stránce terminologie.

Jinak bych se hrozně rád nějak podílel na vývoji učebnice, leč "programuji" v PHP teprve rok, tak bych si troufl pouze na nějaké začátečnické téma. Pokud něco zbyde, rád navrhnu nějakou kostru a zbytek může dopsat kolektiv.

Rád se budu podílet na celkové korektuře učebnice. Mám za sebou několik manuálu, tak bych snad mohl být užitečný :-)

P.S. možná tento můj koment patří do nějaké jiné kategorie, tak mě prosím kdyžtak přesuňte ;-)

abc:
„by asi mohl být pod každou kapitolou odkaz na "terminologii", kde by byly tyto cizí termíny vysvětleny.“
Taky už jsem o tom přemýšlel.

Možná ale ještě lepší řešení by bylo držet si seznam termínů jen interně a vysvětlivky zobrazovat jako tooltip.
Připíšu to k redakčnímu systému.

Další revize návrhu, zkusil jsem to doplnit a některé věci naopak zestručnit:


• Téma příkladu by mělo být široce srozumitelné, nekontroverzní a nemělo by odvádět pozornost od vykládaného problému. Příklady lze ozvláštnit zajímavými originálními problémy, ale jejich pochopení nesmí vyžadovat detailní znalosti např. děje či postav knihy, filmu, televizního seriálu a podobně.
• Veškerý kód musí být kompatibilní s PHP verze 5.3 a novější. Výchozí instalace serveru bude popsána v samostatném článku a hlavní text by měl s takovou instalací a nastavením počítat. Pokud ale jiné v praxi rozšířené nastavení vede k odlišnému výsledku kódu, mělo by to být zmíněno.
• Příklady nesmějí generovat chybové hlášky žádné úrovně s výjimkou těch, které generují záměrně jako součást výkladu. Pokud demonstrovaná funkčnost vyžaduje rozsáhlejší kontext už dříve v článku zmíněný, je možné v ukázce uvést jen relevantní kód s popisem, jaký kontext se očekává. Kód nevhodný pro reálné použití (např. ukázka nesprávného postupu) může být záměrně uveden tak, aby po bezmyšlenkovitém zkopírování a vložení nefungoval.
• Funkčnost, jejíž použití se nedoporučuje anebo kterou je v plánu označit „deprecated“ by příklady neměly používat ani v případě, že zatím E_DEPRECATED negeneruje.
• Kód se uzavírá do standardních značek PHP, tedy <?php … ?>
• 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, NejakaTrida::nejakaVlastnost)
• Konstanty se pojmenovávají velkými písmeny s podtržídky (MOJE_KONSTANTA)
• Příkazy se píší na samostatný řádek, nespojují se dohromady na jeden řádek.
• Ve výrazech se kolem operátorů píší mezery ($y = ($x + 1) / 2;)
• Řetězce se dávají do apostrofů nebo uvozovek podle toho, co je praktičtější. Výchozí je apostrof.
• Bloky kódu se odsazují 4 mezerami.
• U řídicích struktur s alternativní syntaxí (např: if(podmínka): kód; endif;) se preferuje syntaxe se složenými závorkami (tj.: if (podmínka) { kód }), podmínka je uzavřena do závorek, před kterými se dělá mezera. Za složenými závorkami se dělá odřádkování, s výjimkou konce bloku IF následovaným částí ELSE:
• U příkazu switch je odřádkování za částí case a příkaz break je na zvláštním řádku a odsazený o 1 úroveň oproti case. Pokud se pokračuje do další větve vynecháním příkazu break, musí na to upozornit komentář:

• Příklady nesmějí obsahovat zhuštěné špatně čitelné konstrukce, případně konstrukce spoléhající 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.
• 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ářů.
• 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.

Možná by stálo za zvážení, zda rovnou nedodržovat PSR-0, PSR-1 a PSR-2. Většina bodů je tam rozumných.

Se štábní kulturou bych to moc nepřeháněl. Stejně se nikdy netrefíte do vkusu všech, což je vidět i zde. Stačí, když jeden člověk udělá kompletní návrh a ostatní se mu v tom přizpůsobí (pokud teda nebudou jo zásadní výhrady).

Každopádně samotný vývojář si pak ve vlastním kódu stejně vytvoří štábní kulturu sobě na míru.