Názvy proměnných v příkladech dokumentace – česky nebo anglicky?

No, když je to pravidlo nepsané, tak radši počkám, až to potvrdí ještě někdo jiný. ;-) Pak ho doplním do Psaní dokumentace. Nemyslím, že by to patřilo do Coding Standard, protože ten chápu jako doporučení, jak psát i vlastní opravdové programy, nejen příklady do dokumentace. Volbu jazyka bych v případě vlastních projektů nechal na programátorovi.

Čistě akademicky by mě zajímalo, z jakého důvodu jste se pro angličtinu rozhodli.

Neznám asi nikoho, kdo by psal proměnné/komentáře/commit messages česky. Hlavní důvod asi je, že getObjednavka(), případně new Clanek() vypadá blbě, navíc se většinou stejně nedá použít diakritika.

Do diakritiky bych taky nešel, ale jinak myslím, že je to otázka použitelnosti. Jestli je to pěkné nebo ne, vnímá každý jinak. Už jsem viděl dost zdrojáků, kde se chudáci programátoři pokoušeli něco vysvětlit anglicky, ale napáchalo to víc škody než užitku. Programátor ne-Čech by takové pidgin English stejně nerozuměl.

Nemá smysl si hrát na to, že zrovna můj projekt bude jednou upravovat nějaký cizinec. Můžete namítnout, že si zbytečně zavírám vrátka, ale je to otázka pravděpodobnosti. Daleko pravděpodobnější v určitém kontextu může být, že ho bude upravovat programátor, který bude psát tak blbě anglicky, že jeho komentáře budou bláboly a názvy proměnných zavádějící. A nejhorší jsou pravopisné chyby, třeba taková db tabulka refferals.

Zdrojáky Nette by měly být komplet v angličtině, ale já jsem tohle vlákno otevřel kvůli proměnným v příkladech. Komentáře máme česky, tak proč proměnné ne?

@HosipLan: Mluvíš teď o mých dnešních korekturách v Routingu?
Možná sis nevšiml kontextu. Tohle je příklad, o kterém se bavíme:

// staré URL /product-info?id=123
$router[] = new Route('product-info', 'Product:detail', Route::ONE_WAY);
// nové URL /product/123
$router[] = new Route('product/<id>', 'Product:detail');

Původně tam bylo Route('produkt/<id>', což neodpovídalo komentáři nad tím. Z příkladu mi nevyplývalo, že by se jednalo o českou alternativu url k anglické. Proč si to myslíš ty?

Jinak tohle bychom asi radši měli probrat po e-mailu, do tohohle vlákna to nepatří.

@22: Teď ti nerozumím. Co jsem tedy udělal špatně? Vždyť komentář „nové URL“ neodpovídal definici toho nového url. Koukni do historie, měnil jsem jen Route(), ne komentář.

Vůbec s tím nesouvisí, jestli je to česky nebo anglicky. Nevím, proč to HosipLan napsal do tohoto vlákna. Jestli to chcete dál rozebírat, pište mi prosím rovnou nebo založte nové vlákno. Tohle je topic hijacking :-)

A k tomu „počkej, až tomu budeš rozumět“ mám dvě poznámky:

1. Jak poznám, že už tomu teda fakt opravdu rozumím? Ty Nette rozumíš? Fakt?
2. Až tomu budu rozumět, tak se nebudu zpátky vracet a opravovat dokumentaci v místech, kde jsem jako začátečník nechápal, o čem je řeč. Opravovat se to musí hned, jinak to už nikdo neudělá, není čas. Jasně, že občas napíšu blbost a někdo to po mě musí opravit (díky Honzo), ale dělám co proto, abych se tomu vyhnul.

@petr.pavel: proč měníš produkt na product?? Já chci mít v URL produkt, ne product, taková změna je vhodné akorát v anglické verzi dokumentace.

Kdy člověk rozumí Nette? To je těžká otázka, pokud to mám brát jako komplet, tak rok mi nestačil zatím :-)

Ale ani teď si nedovolím v dokumentaci opravovat kod, o kterém si nejsem na 100% jistý, že je to buď starý zápis nebo že je to překlep v kodu.

Jednoduše řečeno, Nette asi umíš/rozumíš, když dokážeš odpovědět na 90% všech dotazů tady na fóru :-)

Editoval 22 (31. 8. 2011 13:20)

@22: Naopak, pořád jsi ještě nepochopil, co jsem vlastně opravil a proč :-)

<ot>
Že tomu rozumíš poznáš tak, že po tobě nebude muset nikdo opravovat faktické chyby

Pokud budeš mít příště nápady na doplnění příkladů, založ stránku na adrese https://blog.nette.org/, rád ti ji zkontroluji.
 </ot>

Názvy proměnných: ok, je vás rozhodně většina :-) Doplnil jsem do pokynů k psaní dokumentace

OT Routing: Příklad ukazoval jak postupovat při přesměrovávání ze starého, již neplatného url na nové. Nešlo o jazyky, mohlo to být klidně z brekeke/id na abrakadabra/id. „produkt“ není český překlad anglického „product-info“.

@Majkl578 > tyjo tak to je bomba! :-D Asi vsechny zdrojaky prepisu do cestiny a rovnou i s diakritikou…

Ne vazne, pouzivani ceskych promennych je zlo a michani cestiny a anglictiny jeste vetsi (ikdyz se musim priznat ze komentare mam cesky bez diakrity – ale to je prezitek z byvalyho zamestnani).

Osobně se z kódu snažím v kódu nemít nic česky, protože se mi to prostě nelíbí. A ne, ani v phpDocu v metodách. Nejenže si člověk zlepšuje angličtinu (občas si nějaké to slovo dohledat musíte), ale taky to udržuje jakousi systematičnost a jednolitost.

Proměnné a komentáře česky (pokud to není kód vyloženě za účelem naučit se _základy_ programování) by pro mě osobně byl nezvyk jak prase (a měl bych nutkavou tendenci to refactorovat na angličtinu).

Některé české knihy (vím o pár příkladech od Computer Pressu) překládají ve zdrojáku názvy proměnných a někdy se vyskytne i přeložená funkce… To taky nevede začátečníky tím správným směrem…

@Schmutzka: Není mi jasné, proč myslíš, že jsem si nestanovil pravidla. Tahle diskuse je právě o tom.
Sám v projektech pro Čechy používám češtinu, pro cizince pak angličtinu.

@mkoubik + @Nox: Já takové projekty znám. getObjednavka() a new Clanek() mi blbé nepřipadají. Naopak.

@Majkl578: Názorný příklad, díky, že sis s ním dal práci. Nevím jestli schválně, ale přešvihl's to do druhého extrému. Nette usiluje o rozšíření i mimo ČR, takže zdrojáky Nette by jednoznačně měly být celé v angličtině. Já jsem mluvil o proměnných v příkladech české dokumentace.

Vezměte si třeba příklad z NotORM. Není jasné, jestli application je nějaké jádro mé aplikace nebo NotORM. A hele, ona je to jen databázová tabulka s nešťastným názvem.

$applications = $db->application()
    ->select("id, title")
...

David (nebo kdo) naštěstí správně vyměnil aplikace za knihy, ale ještě srozumitelnější by to celé bylo s českými názvy databázových tabulek a atributů.

{foreach $db->table('kniha')->order('nazev')->limit(5) as $kniha}
    <h2>{$kniha->nazev} ({$kniha->autor->jmeno})</h2>

    {foreach $kniha->related('kniha_znacka') as $znackaKnihy}
        {$znackaKnihy->znacka->nazev}{sep}, {/sep}
    {/foreach}
{/foreach}

Hned je vidět, co je systém a co data. Uvažujte z pohledu začátečníka. Stojí před neproniknutelnou hradbou vzájemně propojených informací a neví, kde začít. Bude vděčný, když mu ušetříte čas.

@gmvasek + @redhead: Právě proto se zastávám knih, které češtinu pro data používají. I pro funkce.

Nejsem si jistý, jestli je možné přijmout argument, že je něco nezvyk. V běžné řeči taky používám anglicismy a jiné patvary, které ale do dokumentace nepatří. Kriteriem by nemělo být, jak snadno se mi to píše, ale jak snadno je text pochopitelný.

Nikdo z vás nepoukázal, že čeština má delší slova, což srozumitelnosti ubírá. Tímto směrem by se měla ubírat argumentace. Ne, že je něco „ošklivé“ – na to má každý jiný názor.

Editoval petr.pavel (4. 9. 2011 15:59)

Tady myslim šlo petr.pavlovi o to, že by si nováček teoreticky mohl myslet že $db objekt má vazbu na nějaký objekt Application… což je sice podivné a nevím jestli by takový člověk byl vůbec ve fázi vhodné pro použití Nette (to není elitismus, každý se musíme učit), ale není to zase tak úplně mimo

petr.pavel napsal(a):

@mkoubik + @Nox: Já takové projekty znám. getObjednavka() a new Clanek() mi blbé nepřipadají. Naopak.

Název metody getObjednavka je podle mě ideální příklad toho, jak ošklivé je kombinovat češtinu a angličtinu na jednom místě. Podobně jako např. ObjednavkaControl. :)

@Majkl578: Názorný příklad, díky, že sis s ním dal práci. Nevím jestli schválně, ale přešvihl's to do druhého extrému. Nette usiluje o rozšíření i mimo ČR, takže zdrojáky Nette by jednoznačně měly být celé v angličtině. Já jsem mluvil o proměnných v příkladech české dokumentace.

Jistěže schválně. Chtěl jsem poukázat na to, jak může být český kód odpudivý.

Nox napsal(a):

Tady myslim šlo petr.pavlovi o to, že by si nováček teoreticky mohl myslet že $db objekt má vazbu na nějaký objekt Application… což je sice podivné a nevím jestli by takový člověk byl vůbec ve fázi vhodné pro použití Nette (to není elitismus, každý se musíme učit), ale není to zase tak úplně mimo

Takovéhle potencionálně zavádějící pojmenování by se buď neměly používat vůbec, nebo by v předchozím textu / komentáři měly být jasně vysvětleny.