Přejít k navigační liště

Zdroják » Různé » Jak psát hezký kód I

Jak psát hezký kód I

Články Různé

Programování nespočívá jen v zapsání algoritmu v určitém programovacím jazyku tak, aby výsledek fungoval – tedy syntakticky a sémanticky správně. To je u programování samozřejmost. Programátoři ale často zapomínají, že po nich budou číst kód i jiní, někdy i oni sami. Napsat kód nejen správně, ale i „hezky“, pak ušetří spoustu práce.

Seriál: Hezký kód (3 díly)

  1. Jak psát hezký kód I 13. 4. 2010
  2. Jak psát hezký kód II 20. 4. 2010
  3. Jak psát hezký kód III 27. 4. 2010

Nálepky:

Jak psát kód hezky nelze jednoduše říct, protože každý, opravdu každý, kód lze napsat lépe, než jak momentálně vypadá. Ať už se snažíme sebevíc, vždy je možnost, jak ho vylepšit. Nikdy proto nenapíšeme bezvadný kus kódu, ale to neznamená, že na psaní hezkého kódu máme rezignovat a psát špatně kód, který nelze znovu použít. Existuje několik všeobecných zásad, které pokud dodržíte alespoň trochu, tak se bude váš kód lépe číst nejen vám, ale i ostatním lidem, kteří ho budou používat, upravovat či jen pročítat. Nemluvě o dobrém pocitu z dobře odvedené práce.

Než se pustíme do samotných zásad, tak je na místě upozornit, že nelze psát pěkný kód ihned. Nejprve je třeba napsat kód „na hrubo“ a poté ho upravovat, dokud nebude dobrý. Zdůrazňuji slovo dobrý, protože kdybyste chtěli kód upravovat do ideálního stavu, tak u něj dříve umřete.

Já osobně nejprve napíši nějaké monstrum podle zadání (dílčí část, nikoliv celou aplikaci – upravit kód celé aplikace znamená napsat jej všechen znova a lépe), poté se pozastavím a zamyslím se, zda by to šlo upravit a jak. Upravit to lze samozřejmě vždy a záleží na daném problému, jak to udělat. Rozmyslím se, kód upravím a opět se na něj podívám, zda je dobrý nebo zda potřebuje ještě nějakou úpravu. Takto se to opakuje, dokud nejsem s výsledkem spokojený. (Čas od času se stane, že z původního monstra nic nezůstane a vše se změní, samozřejmě k lepšímu.) Až poté pokračuji dál s další částí. – pozn.aut.

Hezký kód

Definovat nějak hezký kód, jak bylo řečeno, nelze a nikdy to ani nepůjde. Záleží na každém kodérovi, jak si definici vytvoří. Můj pohled na čistý kód je takovýto: „Čistý kód je takový kód, který dělá přesně to, co očekáváte. Je to takový kód, který lze dobře číst, a který lze číst bez skákání.“ Pojem Čistý kód mám ze stejnojmenné knížky od Roberta C. Martina a doporučuji ji mít ve své knihovničce všem, kteří to s programováním myslí alespoň trochu vážně.

Názvy proměnných, funkcí, tříd

Pokud začnete programovat v jakémkoliv jazyce, tak začnete s vytvořením proměnné, do které hodíte nějaký řetězec, většinou „Hello World!“, a pozdravíte svět. Je to logické, že se nezačne uprostřed, třeba se zachytáváním výjimek, a proto já také začnu u proměnných, resp. názvů proměnných, ale i funkcí, tříd, …

Názvy proměnných by měly být určeny podle toho, jakou informaci v sobě nesou. Názvy funkcí naopak podle toho, co funkce provádí. Podobné pravidlo je vhodné dodržovat pro všechny věci, které se nějak pojmenovávají. Některé věci se pojmenovávají standardně, chcete-li stejně, u ostatních se musíme dobře rozmyslet. Podívejte se na následující příklad:

def zjistiJestliJeTentoRokPrestupny( x ):
    if x % 4 == 0:
        return True
    return False

Pozn: Algoritmus je pouze ilustrační a nezohledňuje výjimky z pravidel, např. že přestupné nejsou roky dělitelné 100, pokud nejsou zároveň dělitelné 400. (V tomto článku bude veškerý ukázkový kód v Pythonu.)

Z příkladu je vidět, že takovéto názvy se do kódu nehodí. Název funkce je velmi dlouhý a nikoho nebude bavit ho psát, natož pak zjišťovat proč to nefunguje a hledat ve volání funkce překlep. Vhodný název by mohl být třeba tento: jePrestupny. Argument, kterým se předává rok, je naopak zase moc krátký a hlavně nicneříkající. Pokud se podíváme na tělo funkce, tak vůbec nemáme tušení, co v tom x je za hodnotu a musíme se podívat do hlavičky funkce. Zde by byl vhodnější například název  rok.

Zapamatujme si tedy, že není vhodné používat zbytečně dlouhé názvy, a také se vyhněte používání jednopísmenných, nic neříkajících, názvů. Podívejte se na další příklad:

def secti( l, x ):
    a = 0
    for v in l:
        if v[0] == x:
            a += v[1]
    return a

Po přečtení asi vůbec netušíte, co se může dít. Podle názvu funkce tušíte, že se bude něco sčítat, ale nevíte co a jak. Porovnejte tento příklad s následujícím, který je úplně totožný, až na to, že jsou jiné názvy. Hned se to čte lépe, že?

def soucetHodnotSID( pole, id ):
    soucet = 0
    for polozka in pole:
        if polozka[ID] == id:
            soucet += polozka[HODNOTA]
    return soucet

I dobré pravidlo má rozumné výjimky. Jako odstrašující příklad uvádím firmu, která do svých „coding rules“ dala pravidlo, že v kódu nesmí být použity jednopísmenné proměnné. Nikde, nikdy, basta! Vedlo to k tomu, že programátoři psali např. cykly jako for (promennaCyklu=0; promennaCyklu<50; promennaCyklu++) Zrovna řídicí proměnné cyklů FOR jsou už desítky let běžně pojmenovávány I, J, … takže v tomto případě nadělá rigidní lpění na pravidle spíš víc škody než užitku. – pozn.red.

V předchozím příkladě si můžete všimnout použití konstant. To je také velmi důležité. Místo nesmyslných čísel rozházených všude možně v kódě použijte konstantu, která řekne víc než samotné číslo. Metoda v příkladu pod tímto odstavcem ukazuje změnu šířky – víte, proč se to násobí 39? Ne? No přeci protože 1 cm = 39 px (na mém monitoru) a my kreslíme v měřítku 1:1. Mnohem lepší by tam byla konstanta, pojmenovaná třeba PXNACM, než číslo. Používejte konstanty všude tam, kde je to vhodné.

class Meritko1ku1( Kresleni ):
    ...
    def zmenSirku( self, novaSirka ):
        self.sirka = novaSirka * 39
    ...

Funkce

Jak psát funkce byste možná dokázali odvodit z předchozích textů. Funkce by měla mít nějaký popisný název, který však bude rozumě dlouhý. Název by měl odpovídat tomu, co funkce dělá, a funkce by měla dělat pouze tu věc, kterou má napsanou v názvu. Pokud například funkce získává data z nějakého zdroje, neměla by při tom něco nastavovat. Podívejte se na příklad:

class Kosik:
    ...
    def pridatDoKosiku( self, produkt ):
        self.vyprazdnitKosik()
        self.kosik.append( produkt )
        return self.kosik
    ...

Asi byste podle názvu tipovali, že metoda přidá do košíku výrobek a popřípadě vrátí logickou hodnotu, zda se to povedlo či nikoliv. Možná si to myslíte, ale metoda vás pěkně obelstí, protože před přidáním celý košík vyprázdní a ještě k tomu vrátí obsah košíku. Takovou hrůzu by asi nikdo nenapsal (autor je optimista – pozn.red.), ale je spousta funkcí, které dělají velmi neočekávané věci – a to je špatně!

Vyvarovat se psaní funkcí, které dělají věci navíc, lze třeba tím, že se budeme držet dalšího pravidla: Pište funkce malé. Pokud budeme psát malé (krátké) funkce, tak se nám nestane, že bychom napsali funkci, která dělá spoustu dalších, nečekaných, věcí. Funkce by měla dělat jen jednu věc a dělat ji řádně – a to zvládne spíš malá funkce. Z vlastní zkušenosti mohu říci, že dlouhé funkce jsou náchylnější na chyby než ty krátké, a daný úkol nezvládají dělat dobře.

def ziskatAkcie( symbol='GOOG' ):
    url = urllib.urlopen( 'http ://download.finance.yahoo.com/d/quotes.csv?s=%s&f=nl1c1' % symbol )
    data = url.read()
    akcie = data.split( ',' )
    nazevSpolecnosti = akcie[0].split( '"' )[1]
    posledniObchod = akcie[1]
    zmena = akcie[2]
    return {
        'nazevSpolecnosti' : nazevSpolecnosti,
        'posledniObchod' : posledniObchod,
        'zmena' : zmena,
    }

Určitě vidíte, co je špatně: I když funkce dělá, co se od ní očekává, stejně provádí nějaké operace navíc. Lepší by bylo určité činnosti rozdělit do menších funkcí/metod, zhruba následujícím způsobem (metody zde rozepisovat nebudu, to není pro ukázku důležité).

class Kurzy:
    ...
    def ziskatKurz( self, symbol ):
        self.nastavitSymbol( symbol )
        self.ziskatData()
        self.parsovatKurz()
        return self.kurz
    ...

Dalším dobrým pravidlem je, že funkce by měla mít co nejméně argumentů. Ideální jsou funkce, které mají dva a méně argumentů. Pokud má vaše funkce více argumentů než např. pět, je na místě se zamyslet, zda to je v pořádku a zda to nelze udělat lépe. Může ovšem nastat situace, kdy je nutné tyto argumenty předávat – pak zvažte, zda skupinu argumentů nebude vhodnější předávat jako objekt. Příkladem může být předávání souřadnic.

vykresliKouli( x, y, z, r )

bod = Bod( x, y, z )
vykresliKouli( bod, polomer )

Závěr

Z dnešního dílu by měla být jasná následující pravidla:

  • Názvy by měly být popisné.
  • Používejte konstanty.
  • Funkce by měly být krátké.
  • Funkce by měly dělat jednu věc a pořádně.
  • Funkce by měly mít co nejméně argumentů.

Příště se podíváme na objekty, komentáře a formátování.

Poznámka redakce: U pravidel pro psaní „hezkého kódu“ platí snad víc než kde jinde zlaté ponaučení o uměřenosti: Každé pravidlo musí být důsledně aplikováno vždy a všude, pokud je to v rozumné míře. Právě pravidla „hezkého kódu“ ráda sklouzávají v praxi do dogmatických výkladů, kdy se z nich stává spíš noční můra kodérů. Pravidla uvedená v článku jsou obecně platná, ale pokud zrovna ve vaší firmě máte jiná, jistě je máte z dobrého důvodu. 

Komentáře

Subscribe
Upozornit na
guest
93 Komentářů
Nejstarší
Nejnovější Most Voted
Inline Feedbacks
View all comments
Makovec

Jakkoli s nimi v principu souhlasím, myslím si že tam nemají co dělat: buď je zařadí do textu sám autor během editorského procesu, a nebo si je nechte do diskuse případně od cesty. Tahle z autora děláte tak trochu troubu.

iki

+1, ty poznámky se spíš hodí do komentářů

Martin Malý

Autor dostává před publikováním náhled článku i s těmito poznámkami, a má prostor se k nim vyjádřit.

13. 4. 2010 9:17 redakčně upravil Martin Malý, důvod: Zestručnění komentáře kvůli jednoznačnosti
ahl

+1
Třeba ten první komentář vypadá, jakoby tomu autor vůbec nerozuměl a snažil se laicky popsat test driven development.

Martin Malý

Ta první poznámka – myslíte autorskou poznámku („já osobně nejprve…“)?

ahl

ano.

ahl

Až teď jsem si všimnul, že jsem reagoval na něco jiného než jsem myslel:)

Aleš Roubíček

Už jsem se radoval, že bude zajímavý článek, jenže velké zklámání už u první ukázky kódu.

Používání češtiny ve zdrojovém kódu je jednou ze základních chyb proti čistému kódu. Čistý kód píšeme tak, aby byl výsledek dobře čitelný a srozumitelný, nejlépe jako lidská věta. Pokud ale mícháme anglické kustrukce jazyka s českými názvy proměnných, tříd a metod, je veškeré snažení k ničemu!

Jediná kniha, kterou o Pythonu vlastním, šla až tak daleko, že v ukázkách kódu překládala do češtiny i klíčová slova jazyka. K čemu pak takový kód je si můžemete domyslet sami.

Honza Vrana

Krasny den,

to ovsem plati za predpokladu, ze anglictinou vladnete natolik dobre ze je „výsledek dobře čitelný a srozumitelný, nejlépe jako lidská věta“.

Pokud anglictinu neovladate tak budete u kazde funkce sedet se slovnikem aby jste funkci pojmenoval. Pripadne pri cteni kodu hledal ve slovniku co ta funkce vlastne dela. To si pak tou anglicctinou kod velmi zprehlednite.

A myslim ze k tomu aby cloveku dosla slovni zasoba staci jen trosku specializovana aplikace.

Samozrejmne pojmenovani funkci cesky v podstate zabranuje predani kodu necesky mluvicim programatorum.

A taky na tom nesmite bejt s cestinou jako ja, to pak mate problem napsat i
cesky dvakrat za sebou stejny nazev funkce :D.

s pozdravem Jan Vrana

PS: v preklad kodu v te knize opravdu vygeneroval spoustu chybneho kodu. A souhlasim ze se prekladat nemel. V clanku me to neurazi, autorovy slo o vysvetleni principu. Pokud chcete psat nazvy v anglicctine nebo esperantu, jiste Vam nebude cinit problem princim aplikovat i na tyto jazyky.

neron

Ne a ne a 100× ne :) Ja umim anglicky mizerne, s nazvama funkci zapasim porad, ale ani me nenapadne psat je cesky – zvlast v Jave pak getry a setry vypadaji priserne (getJmeno, isZalozeny atd.).

Neco jineho jsou komentare v anglictine, s tim mam taky problem.

Jeste bych mel poznamku k: soucetHodnotSID() – doporucil bych spis soucetHodnotSid(), tady to nevadi, ale pokud je zkratka uprostred nazvu a nebo jsou dokonce 2 za sebou, vyrazne to snizuje citelnost.

ahl

A v jakém jazyce píšete komentáře? Podle mě by měl každý psát v tom jazyce, který umí a ne se slepě honit za nějakým ideálem, když se potom v kódu nevyzná nikdo. Většina Čechů, kteří si myslí, že anglicky umí, používá dialekt nazývaný Czenglish, který je srozumitelný pouze Čechům a to často jenom s obtížemi.

neron

Kdyz o tom rozhoduju ja, pisu je cesky, kdyz jini a voli anglictinu, pouzivam czenglish :)

Aleš Roubíček

S komentářema si hlavu lámat nemusíte, pokud píšete dostatečně popisný kód jsou komentáře zbytečné. Komentáře totiž mají tu vlastnost, že se většinou s okolním kódem neudržují, tudíž velice rychle zastarávají.

Samozřejmě u dokumentačních komentářů je to věc jiná a tam pak jde o domluvu v týmu, jakým jazykem se dokumentace píše.

alejo

Taky názor. Já třeba udržuju dostatečně aktuální i komentáře. Btw, nedávno jsem četl rozhovor s nějakou programátorkou (už nevím s jakou a kde), a ta taky nepíše komentáře, prej „kód by měl bejt jasnej sám o sobě“. Podle mě to jsou kecy, a bez komentářů si to ani za ta léta nedovedu představit. A ani nemusim, a nechci. Vyznám se v tom i po letech mnohem rychlejc než bez nich, a to v řádově kratším čase, i úpravy a opravy jsou pak mnohem rychlejší a odladěnější, než kdybych čučel jen na holej kód (kterej si myslim, že nemám ošklivej).
Navíc je spousta výjimek, co kde jak kdo udělá za konstrukci třeba, a má pro to důvod. A kam to asi hodí – do komentáře, jistěže, to by byl magor, kdyby ne, a myslel by si, že si to 1000× takhle zapamatuje nebo co.

Aleš Roubíček

Ano takové důvody přesně patří do dokumentačních komentářů.

Komentáře typu „načtu uživatele z DB“, „zahashuju heslo“ jsou pouze šum který je čitelný i z kódu. Navíc přináší režii udržování jak výkonného kódu, tak komentářů. A přitom jsou takové komentáře snadno nahraditelné vlastní metodou, jejíž název nese stejnou informaci jako text komentáře. ;)

BTW zkuste si knihu – v úvodu článku zmiňovanou – přečíst. Tam je to vysvětleno v širším kontextu.

s

ten programator byl RMS. Meli sme v praci jednoho cloveka, co vsechno komentoval. Priklad vypadal asi takto: (Aby tomu tady vsichni rozumeli prekladam do cestiny):

/*
* autor: Marek Vopicka
* datum: 1.1.2009
* projekt: Databaze Informacniho Systemu
* firma: Vrcholove vedeni 2000
* popis funkce: tato funkce napise retezec
*/
void NapisRetezec()
{

}

nebudete tomu verit, ale je to na zabiti.

František Kučera

Doporučuji knihu Dokonalý kód – tam je pěkně popsáno, které komentáře smysl mají a měly by se psát a které smysl nemají a jen otravují. (tenhle kód spadá do té druhé skupiny)

petan

Množství a význam komentářů je závislé na délce praxe. Začátečník komentuje třeba i nějaké spojení dvou polí ve stylu „toto spojí pole A s polem B“. S postupem času se komentáře především významově změní ….. a komentují se složitější konstrukce. Už se nekomentují co jednotlivé příkazy udělají, ale komentuje se PROČ jsem to udělal.

František Kučera

„pokud píšete dostatečně popisný kód jsou komentáře zbytečné“

To si nemyslím* – komentář by měl vystihovat smysl daného kusu kódu, tedy nepopisovat, co děláme (např. sečteme proměnnou „a“ a „b“ a dosadíme do „c“ – to si skutečně člověk přečte z kódu, na to není potřeba komentář), ale proč to děláme, jaký je ten „byznys“ smysl.

*) osobně mi spíš přijde, že tohle tvrdí programátoři, kteří jsou buď líní psát komentáře, nebo se nechtějí podělit o své znalosti s ostatními členy týmu a být „nenahraditelní“. Ale nechci se nikoho dotknout :-)

Aleš Roubíček

Většina „dobře okomentovaného kódu“ obsahuje převážně popisné nebo zastaralé komentáře. Tedy škváru. O své byznys důvody se podělíme v dokumentačních komentářích přímo v kódu nebo jsou součástí analýzy či jiné dokumentace.

Čistý kód píšeme právě proto, abychom nebyli nenahraditelnými, ale by se s kódem dobře pracovalo. Na předávání svých znalostí kolegům jsou jiné a lepší cesty.

dingo

Já si nemůžu pomoci, ale kdo věnuje programování množství času větší než malé, tak stejně musí číst min. dokumentace a různé články, které jsou v češtině většinou ve velmi omezeném množství a nezbývá než je otevřít v angličtině. Tady je, alespoň elementární, znalost angličtiny přinejmenším nutná. Osobně se mi v kódu objevuje čeština maximálně jako obsah nekterých stringů (které se pak ukazují ve výstupu html) a to jestě zavírám oči a přemýšlím, jak by to šlo udělat jinak.
Konvence kódu jsem si zažil (Díky Davide) takhle:

  • function_name()
  • variable_name
  • ClassName
  • CONSTANT_NAME
uf

mas pravdu. Tvrdim, ze pro cteni bezne pouzivane anglictiny staci prvnich 5–8 lekci (teda z hutnejsi ucebnice, ja jsem napr. mel Anglictinu pro vedecke a odborne pracovniky) + slovni zasobu ziskate casem.

Aleš Roubíček

Asi vás zklamu, ale bez angličtiny se v tomto oboru neobejdete. Čím dříve na to příjdete, tím lépe. Je pravd, že ze začátku budete potřebovat slovník, ale i tak se dá něco naučit. A náš obor je především o učení ;)

Murdej

Právě tím „čuměním do slovníku“ jsem se naučil z dost velké části anglicky.
Ale jsou i horší věci než používání češtiny, třeba kombinování čestiny a angličtiny. Občas vydím takové špeky jako get_nazev a ve stejnem souboru potom UkazTitle.

uf

ty pys radsi anglicky

s

Nechci se te dotknout, ale odhadoval bych te tak na 15 let. Tva oblibena zabava je HTML/PHP. Tvoje oblibena kniha je PHP za 80 dni. Na vecernicka uz koukas jen kdyz se tam mluvi.

František Kučera

„Pokud ale mícháme anglické kustrukce jazyka s českými názvy proměnných, tříd a metod, je veškeré snažení k ničemu!“

S tím bych si dovolil nesouhlasit. Čeština v kódu vede k tomu, že je na první pohled zřejmé, co jsme psali my (resp. co je kód aplikace) a co jsou konstrukce jazyka nebo standardní knihovny. Čeština má i další výhody. Ale i nevýhody, to nezastírám. Viz Proč psát programy česky?

Aleš Roubíček

Do Clean Code prostě národní jazyky nepatří a řekl bych, že ani britská angličtina tam nemá místo. Chápu, že mnoho lidí si dokáže odůvodnit jakoukoli blbost, ale nespojujme to s čistým kódem, který má být srozumitelný pro všechny.

Martin Malý

K tomu jen připodotknu: Mnohokrát jsem se setkal s open source kódem, kde bylo napsáno anglicky, co to dělá, a za odkazem DOWNLOAD byla poznámka: „Komentáře v kódu jsou bulharsky (maďarsky / portugalsky / řecky / japonsky), ale smysl je snad jasný“. Bohužel, maďarský komentář u maďarské proměnné opravdu smysl nedával.

*) doplňte libovolný dostatečně cizí jazyk

František Kučera

„Chápu, že mnoho lidí si dokáže odůvodnit jakoukoli blbost, ale nespojujme to s čistým kódem, který má být srozumitelný pro všechny.“

Kód nikdy nebude srozumitelný pro všechny, to je nedosažitelná meta. Někdo je negramotný nebo nemá obecné počítačové a analytické znalosti, aby rozuměl jakémukoli kódu, někdo neumí daný programovací jazyk, někdo neumí česky, někdo anglicky nebo rusky… Skupina čtenářů našeho kódu je vždycky omezená. Když píšeme kód česky, je samozřejmé, že si v něm počtou primárně Češi – pokud jsme s tím smířeni nebo je to dokonce záměr, pak je použití češtiny naprosto v pořádku (a výhodné).

Aleš Roubíček

To je právě jádro pudla, čtenář čistého kódu, nepotřebuje mít znalosti programovacího jazyka ani analytické ani jiné počítačové znalosti, přesto bude tušit, co ten kód dělá, protože, když se čte, dává smysl. Toho efektu se nikdy v národních jazycích nedočkáte (pokud si nenapíšete vlastní jazyk).

František Kučera

To je jen iluze, že by šel program číst jako věty v přirozeném jazyce. Částečně o to usiloval BASIC, částečně to tak funguje v SQL (VYBER co… Z tabulky… ZA PODMÍNKY, ŽE …), ale obecně to nemá moc smysl o takovou pro čitelnost laiky (lidi, kteří neznají žádný programovací jazyk, nemají analytické myšlení atd.) usilovat – program není slohovka ani román.

aprilchild

Hezky blogpost, ale stejne je cestina ve zdrojacich predmetem podobne pitomosti a kratkozrakosti jako pousteni cizich filmu s dabingem bez moznosti originalu (a titulku) v TV. Oboji vede jen k tomu, ze se nikde nedomluvite. Zeptejte se kterehokoliv Skandinavce, proc umi anglicky. Lpeni na cestine v „novych“ oborech je nesmysl. Psani kodu v narodnich jazycich zlo. :).

Jiří Knesl

Bohužel Franto, čeština je naprosto okrajový, ve světovém kontextu nezajímavý a nepoužitelný jazyk. Každá firma/startup, která byť jen pomýšlí na to, že poroste do zahraničí, si nemůže dovolit psát komentáře, vcs commit messages, user stories a cokoliv dalšího v ničem jiném, než je angličtina. Netýká se to ale jen těchto firem – například Brno je plné slovenských studentů. Několik let jsem pracoval se Slováky v týmu. Co obnáší, že nenasadíš povinou angličtinu? Máš půl kódu česky a půl slovensky (teda tu půlku, co si píšeš sám – ostatní příkazy jsou anglicky).

To, že nsk nějaký vývojář neumí dobře anglicky, to je hodně velká ostuda. Pochopil bych to před 20 lety. Pochopil bych to s určitými výhradami před 10 lety, ale dnes se může jít programátor, který neumí anglicky, zahrabat. A že neumí business slovník? Tomu se lze snadno vyhnout:

vymyslím si příklad: e-shop s erotickými pomůckami.
Musím znát anglické názvy všemožných pout, bičíků, afrodiziak apod.?

Ne, stačí mi ProductsController, Product model a složka products view (popřípadě jak to který framework má).

Za dobu, co programuju, jsem měl pouze jednou problém s angličtinou. Když jsem psal web autobazaru a byly tam různé parametry automobilu (zdvih apod.) – to si člověk ale pamatovat nemusí, zobrazovalo se to na 2 (slovy DVOU) místech – ty důležité věci byly abstraktnější – a tedy i známější slova.

František Kučera

Ad „Každá firma/startup, která byť jen pomýšlí na to…“

a „Netýká se to ale jen těchto firem – například Brno je plné slovenských studentů.“

Vždyť to v tom blogu píšu, stačí si ho přečíst :-) Viz:

„Pokud si brousíte zuby na to, že ten software jednou prodáte nějaké americké firmě za těžké prachy, s česky psaným zdrojovým kódem byste asi moc neuspěli.“

„Uvažujete-li o najímání levných nevolníků třeba z Indie, angličtině budou rozumět lépe než češtině (ale beztak to není moc šťastný nápad). Politicky korektně řečeno: plánujete-li práci v mezinárodním tý­mu.“

Ad „vymyslím si příklad: e-shop s erotickými pomůckami.
Musím znát anglické názvy všemožných pout, bičíků, afrodiziak apod.?“

Ne všechny aplikace/systémy jsou tak jednoduché jako „e-shop s erotickými pomůckami“ nebo web bazaru. To jsou v podstatě generické aplikace, kde je té byznys* logiky minimum.

Tím nechci říct, že složitější/od­bornější aplikace by se musely psát česky, to ne. Ale když už se zvolí angličtina, dělejme to prosím pořádně – důkladná analýza, kvalitní slovníky schválené zadavatelem. A hlavně připravené předem – ještě než na tom začne vyšívat programátor. Na tohle se ale spousta týmu vykašle nebo není schopná to zorganizovat a podle toho to pak dopadá (píše se czenglish, lidi si nerozumí, dělají chyby…).

*) myslím takovou, která má skutečnou vazbu na daný obor – ne byznys logiku tak obecnou, jako je „prodám položku, expeduji položku…“ kde položka je cokoli, je mi jedno, co to je (a tudíž ani nemusím vědět, jak se to řekne anglicky).

Jiří Knesl

„Vždyť to v tom blogu píšu, stačí si ho přečíst :-)“

Já to četl. Jenže zatímco ty to možná vnímáš jako „jemnou omezující podmínku“, která nezasáhne moc týmů, já to vnímám jako něco, co se týká velké většiny firem – a znemožňuje tedy většině firem použití češtiny.

„píše se czenglish“

Tak to ale nemusí být. Slovník může být v aplikaci diametrálně odlišný, než jazyk exponovaný ve view pro uživatele. Architekturální názvy jako XXXFactory, MSSQLAdapter, UsersController jsou věci, které jsou IMHO pro průměrného programátora čitelnější, než:

TovarnaNaObjek­tyImplementuji­ciXXX, AdapterProMSSQL, OvladacUzivatelu

Business logika jsou pořád jen malé třídy, které dělají jednu jednoduchou věc a je proto snadné je pojmenovat.

Žádost předem definovaného slovníku lze rovnou zahodit. Něčeho takového v praxi nikdy nedosáhneš – pokud nepojedeš typický vodopádový model.

František Kučera

Už to nechci moc rozvádět, protože je jasné, že tohle je jeden z těch flamů, který nemá ani konec ani řešení. Ale jen k těm metodikám:

Tehdy jsme prakticky vodopádovitě* jeli, akorát nebyl čas/energie sehnat ty překlady včas. Nechci to nijak zveličovat, k žádné katastrofě nebo selhání projektu nedošlo – jsou to prostě jen takové detaily a nedokonalosti, které člověku otravují život, berou čas, jistotu a soustředění… věřím, že kdyby se podařilo lidi popohnat a sehnat ty překlady dřív (když už to muselo být anglicky), vyšel by projekt levněji/rychleji.

Docela inspirativní mi přijde OpenUP (otevřený následovník RUPu, agilní metodika): Glossary:

This artifact defines important terms used by the project. The collection of terms clarifies the vocabulary used on the project.

These are the purposes of this artifact:

  • To record the terms that are being used on the project so that everyone has a common understanding of them
  • To achieve consistency by promoting the use of common terminology across the project
  • To make explicit different stakeholders‘ use of the same terms to mean different things or different terms to mean the same thing**
  • To provide important terms to the Analysis and Design team.

Impact of not having:
Misunderstandings about the meanings of data items account for many failed projects. Increased costs and delayed schedules are associated with projects that lack a common understanding of the terms being used.

Reasons for not needing:
On small projects (for example, enhancement projects), which rely on a team very familiar with the terms, this artifact may be omitted.
If a project team has access to the glossary terms in some other form, this artifact may be disregarded.

Slovníček jde utvářet postupně, ale musí se používat konzistentní názvosloví v celém projektu.

*) na straně vývoje i nějaká vůle k agilnějším metodikám byla, na straně zadavatele ale úplně chyběla.

**) tahle věta je divná, co? Ale význam se dá odvodit.

P.S. a to se v té metodice mluví primárně o slovníčku v rámci jednoho jazyka – i tak je vhodné ho mít, natož když máme jazyků víc (lidi od zadavatele moc nezajímá, jaké mají programátoři konvence a jakým jazykem se snaží psát zdrojáky – oni na nás budou mluvit v termínech v tom jazyce, na který jsou zvyklí)

bzuK

„Používání češtiny ve zdrojovém kódu je jednou ze základních chyb proti čistému kódu.“

Primárně nejde o čistotu kódu, ale o efektivitu práce.

Pokud
– jde o vývojový tým českých programátorů
– klient a jeho business logika je v češtině
– nepíšete open source nebo software určený na prodej do zahraničí

a zavedete angličtinu, budou vaši lidé
– psát kód pomaleji a s chybami
– číst kód pomaleji a s chybami

To jsou jenom zbytečné náklady položené na oltář „čistoty kódu“.

Dost pochybuji o tom, že by mix anglických jazykových konstruktů s českým zdrojovým kódem bránil čitelnosti. Naopak je fajn když hned vidíte, co je funkce jazyka/knihoven, a co psal nějaký předchůdce nebo člen týmu.

Aleš Roubíček

Neni.

Národní jazyky ve zdrojovém kódu nejsou obhajitelné. Angličtina se nemusí zavádět, je to standard. Člověk, který anglicky neumí, má smůlu. Takový člověk je neefektivní (z vámi uvedených důvodů). Nnavíc je omezen v možnostech vzdělávání (kvalitních zdrojů v češtině je pramálo, dokumentace frameworků je většinou také anglicky), omezení v znovupoužití již mnohokrát napsaného kódu (opět ekonomicky nevýhodné) atd.

bzuK

Kolik programátorů umí dobře a aktivně anglicky? Odhaduji < 20%.

Zbytek má podle vás možná smůlu, ale programuje;

František Kučera

„Kolik programátorů umí dobře a aktivně anglicky? Odhaduji < 20%.“

Klidně to tak být může, záleží, jak definuješ „umět dobře anglicky“ :-)

Ale podstatnější je něco jiného než obecná nebo programátorská angličtina – a to slovní zásoba pro daný obor, to je ten problém s několika slovníky, co už jsem tu odkazoval.

Angličtina ve zdrojácích by neměla být dogma, ale něco, k čemu dojdeš* po racionálním zvážení nákladů a výnosů, např. když děláš start-up a plánuješ jeho prodej Amíkům.

*) nebo taky nedojdeš, protože zjistíš, že se ti to nevyplatí a radši zůstaneš u češtiny.

uf

Programator nemusi umet DOBRE anglicky. Z gramatiky potrebuje pasivni znalost, aby pochopil psany text v manualech a tutorialech. Staci 5 az 8 lekci hutnejsi anglictiny, ne nejake vlazne.

Pro zapis trid a metod v cestine nevim. Myslim, ze je to nazornejsi, protoze to jsou objekty z problemove domeny. Na druhou stranu chapu, ze je anglictina standard, protoze pocitace nevyvinul jako prvni Jara Cimrman. Nejhorsi je to mixovat.

uf

jeste jsem zapomnel (pro premiru myslenek a maly buffer), ze pro psani zdrojaku staci slovnik pojmu. Klicova slova se taky clovek musel naucit anglicky, ze?

EskiMag

Článok som začal čítať a v tej chvíli ma napadlo, či bude niekte spomenuté aj testovanie. Pri použití dômyselnej techniky cmd+f a zadaní slova „test“ mi to však v článku nenašlo žiadny výskyt. Chcem sa teda opýtať, či bude autor testovanie spomínať v ďalších dieloch článku, pretože robiť refactoring bez testov je viac škody ako osohu .

Aleš Roubíček

Refactoring z definice bez testů musí fungovat, pokud ne, neděláte refactoring. Tím samozřejmě nechci snižovat důležitost jednotkových testů.

uf

Autor bude citovat to, co nalezne v knize. Clanky budou vycuc z knihy.

mila

1. Dodržujte coding standards

Můžeme se přít, zda je lepší styl camelCase, PascalCase nebo under_scores. Co programátor, to názor. Nakonec na tom tolik nezáleží, důležitá je konzistence. Tu zajišťují coding standards a definuje je většina jazyků. V případě Pythonu je to pep8[1]. Proto funkci nepojmenuji „ziskatAkcie“, ale „ziskat_akcie“. Těžko mě autor bude přesvědčovat, že jeho konvence psaní Pythoního kódu jsou lepší, než ty, co navrhl autor Pythonu.

2. Pište kód anglicky

Opominu-li srozumitelnost kódu za hranicemi naší republiky, důvodem ja opět konzistence. S programovacím jazykem zpravidla dostáváme i standardní knihovnu. Používáme cizí knihovny a frameworky. Psaní kódu v národním jazyce vytváří paskvily jako request.user.ko­sik.append(da­tabaze.vyber(for­m.prvni_poloz­ka)).

Nekonzistenci, ke které používání češtiny vede ukazuje i autor, když některé funkce pojmenovává infinitivem, jiné rozkazovacím způsobem.

3. Neopakujte v názvu metod název třídy

Psát kosik.pridatDo­Kosiku je absurdní. Kam bychom položku asi přidávali, když voláme metodu košíku? Od takto pojmenované metody bych čekal, že přidá celý košík do jiného (sloučit dva košíky).

Podobné názvy často ukazují na špatný návrh, což dokazuje i autor v příkladu metody ziskatKurz. Proč má třída „kurzy“ pojmenovaná množným číslem, nastaven JEDEN symbol (měnu) a JEDEN kurz?

[1] http://www.python.org/dev/peps/pep-0008/

uf

A ktere konvence jsou lepsi?

Ja napr. nemam rad, kdyz je v jave if(podminka){ nahusto. spatne se hleda, ze to je if a spatne se ocima parsuje podminka. Ale vidim to v knihach i v profesional­nim kodu.

Kacer

Okej, som za, pekny kod je vzdy krajsi, existuje milion compresorov, ktore vedia stlacit aj kod skriptovacieho jazyka, ale bolo by dobre, keby ukazky zodpovedali realite, lebo rok 2100 sa blizi a podla vlozenej ukazky ho vyhodnotite ako prestupny, ale on nim nie je, nakolko prestupny rok ak je delitelny 100 musi byt delitelny zaroven 400, teda roky 1600, 2000, 2400, 2800.

Martin Malý

Myslím, že v ukázce šlo o něco zcela jiného než o algoritmus na výpočet přestupného roku, a stejně tak mohlo být v těle napsáno „# … zde se vypočítá přestupný rok…“

Kacer

Suhlasim, ze to nebolo cielom clanku, ale povedzme si, nejaky programator si hlada funkciu pre najdenie prestupneho roku, google mu vyhodi tento clanok a vezme si, wow root.cz je c00l uznavana stranka, takze to bude urcite spravny algoritmus.
Nemyslite?

Míša Hájková

Programátor, který nedokáže zbastlit alespoň jakous takous funkci zjišťující, zda je zadaný rok přestupný nebo není, není programátor :)

honza801

doporuceni syntaxe pro python snad uz je davno napsana, ne?

http://www.python.org/dev/peps/pep-0008/

kodér

No, tak snad je pro programátora mnohem lepší a užitečnější, aby to používat trochu (zcela to je prakticky nemožný) jednotně křížově přes všechny jazyky, než aby pro každej programovací jazyk používal jeho autorem doporučovaný to, co si onen autor myslí bez ohledu na jiný programovací jazyky…
Protože kromě Pythonu používám JavaScript, C++, PHP, Delphi a další jazyky, co doporučuje autor Pythonu je mi celkem ukradený…

Pavel Lang

A právě, v C++ dodržuji pravidla projektu, v Delphi dodržuji Delphi pravidla zavedená ve VCL a do značné míry dodržovaná i autory komponent třetích stran, v Javě zvyky z Javy a v Pythonu dodržuji PEP a proto se v tom vyznají i jiní kodéři než já, kteří nejsou zvědaví na „moje“ konvence.

U Pythonu je to ještě důležitější, než v jakémkoli jiném jazyku, protože v Pythonu konvence jasně říká, tohle je metoda/funkce, tohle třída, tohle konstanta, tohle je privátní proměnná… a to vše na základě formátu identifikátoru.

O PHP nemluvím, ale tam už se také vyvynuly – hlavně u velkých projektů – jisté konvence zavedené projektem a často je vyžadováno, aby patche tyto konvence ctily.

Opravdu nemohu souhlasit, že budu mít jeden univerzální styl a ten lze aplikovat na javascript stejně jako na Python, to si snad nemyslí nikdo.. I když to někdy znamená přepínat styl a občas to dá, hlavně po delší době, trošku práce si ten styl oprášit.

xx

Používáme Gregoriánský kalendář, tak si opravte ten přestupný rok.

Martin Malý

Myslím, že v ukázce šlo o něco zcela jiného než o algoritmus na výpočet přestupného roku, a stejně tak mohlo být v těle napsáno „# … zde se vypočítá přestupný rok…“

xx

Napsáno to tam mohlo být, ale nebylo. Vaše funkce by se měla jmenovat jeDelitelneCtyrma. A nevím, proč tam máte

if x % 4 == 0:
    return True
return False

namísto

return x % 4 == 0
Martin Malý

Do textu jsem doplnil patřičnou poznámku. Proč autor nezvolil přímo „return x % 4 == 0“ vám jistě rád vysvětlí sám; já bych teorii měl.

Aleš Roubíček

skoro bych řekl, že existuje mnohem čistčí zápis:

def isLeapYear(year):
  return True if year % 400 == 0
  return False if year % 100 == 0
  return True if year % 4 == 0
  return False 
Honza Kral

kdyz uz jsme u toho tak nejciststi zapis teto funkce v pythonu je:

from calendar import isleap

Aleš Roubíček

Pythonovský knihovny fakt neznám :) Ale jistě bych to použil, kdybych znal. :)

mciha

ucit nekoho by se melo „spravne“ (tj. „pravdu“)… ne „trochu spatne“, navic spravne reseni neni o tolik delsi, aby se tam nevlezlo.

uf

ale ten algoritmus si od vas muze nekdo oprasknout do sveho programu

Honza Kral

Dekuji za sepsani takoveho clanku, mel bych k nemu jen par poznamek:

skutecne piste vse anglicky, i priserna czenglish s preklepy je lepsi nez kod psany cesky.. (je pole array nebo je to tyc?)

kdyz pouzivate python, dodrzujte jeho standardy (pep-8 predevsim), jmenne i formatovaci. V ukazkach chybi docstringy ktere k hezkemu kodu v pythonu 100% patri, chybi vam i komentare

dalsi velmi podstatny problem je absence osetrovani chyb – jediny netrivalni priklad neni spatne proto ze dela vice veci (to je v tomto jednoduchem priklade stale pomerne OK) ale proto, ze vubec nekontroluje zadne chybove stavy. Muzu dostat asi tri druhy vyjimek a ten kdo me vola to vubec nemuze vedet pokud si neprecte muj kod

lepsi motivaci nechat si poradit bych take mel od nekoho kdo (na zaklade kratkeho pohledu do InfoPanelScre­enlet.py, jedine autorovo dilo ktere jsem nasel)
 – nemixuje UNIX a WIN konce radku v jednom souboru
 – nemixuje odsazovani tabulatory s mezerami (obzvlaste v pythonu),
 – nepise 500 radkove (!!!) metody
 – jehoz kod neobsahuje magicke konstanty bez vysvetleni
 – nema metody ktere vraci ruzne datove type
 – nepouziva prazdny except block (zahazovani vsech vyjimek

a obecne ma vetsi zkusenosti s praci na realnych projektech. Jsem rad ze se nekdo zabyva skutecnou kvalitou kodu, ale tohle je skotecne trochu usmevne…

Martin Malý

Lehce se autora zastanu: Opravdu nepovažuju za důležité, aby v příkladu, který ilustruje pojmenování proměnných či metod byly komentáře a docstringy, nebo aby nějaká „dummy metoda“, na níž se ilustruje „dobré“ a „špatné“ jméno fungovala bezchybně (viz komentáře výše o přestupném roce). Taknějak intuitivně chápu, že když autor chce ukazovat rozdíl mezi jménem „ZjistiJestli­JeRokPrestupny“ a „jePrestupny“, tak že nejde až tak úplně o to, jestli dá do těla metody „mod 4“ nebo kompletní algoritmus…

Totéž platí pro ošetřování chyb – není to cílem článku ani ukázky, cílem ukázky bylo demonstrovat štípnutí kódu na menší jednotky. Psát „Dummy()“, „Foo()“, „Bar()“ a „Ni()“ je sice hezká zvyklost, ale není to až tak názorné.

Trochu mohu souhlasit s výhradou „dodržování standardů“ – ovšem spíš ve smyslu tom, že mohlo být řečeno: „Dodržujte jmenné standardy jazyka či frameworku, než si začnete vymýšlet vlastní“ (a jít příkladem).

Ten závěr komentáře (k osobě autora) mi ale připadá poměrně nedůstojný, a dovedu si představit, že by mohl být, jinak formulovaný, rozhodně přínosnější. Takto to svádí k nic neřešící odpovědi: „OK, a kdy se tedy dočkáme článku od tebe?!“

Honza Kral

Uznavam, ze jsem se nechal unest a za to se omlouvam – jestli to vyznelo jako vytka k autorovi tak to je mi lito, byla to spise vytka redakci zdrojaku.

Autora muzu obdivovat za pomerne slusne napsany clanek ktery ma nejakou hodnotu (byt je tam samozrejme spousta veci co se mi nelibi). S jeho vekem a zkusenostmi je to dobry vykon ktery bych velmi ocenil na jeho blogu kde bych zvolil zcela jiny ton. Pokud se ale podobny clanek obevi na strankach odborneho casopisu, budu mit jine naroky.

Obecne nechapu ceske prostredi kde se uverejni cokoliv od kohokoliv, staci kdyz o sobe nekdo prohlasi ze je odbornik na to ci ono a ejhle, stane se jim a jsou mu vydavany clanky. Skutecne tezce se pak autorum kteri neco skutecne umeji (Karel Minarik, Dan Steigerwald z tech ktere mam to poteseni znat osobne a kteri tu za posledni dobu publikovali) obhajuji jejich nazory ktere JSOU podlozeny skutecnou a hmatatelnou praci kdyz jsou staveni na uroven nekoho kdo je zacatecnik (to neni pejorativni oznaceni, vsichni nekdy zacinali a je obdivuhodne ze i zacatecnik se odhodla k napsani neceho takoveho a je to schopen dotahnout) a schazi mu potrebna praxe.

Martin Malý

Honzo, tohle je diskuse, která do komentářů až tak úplně nepatří. Pojďme s ní na fórum, nebo ji proberme osobně, mailem, … Tady bych diskusi ukončil s tím, že mít v mailu týdně jeden článek od Minaříka a jeden od Steigerwalda, tak si výskám a považuju se za šťastlivce!

uf

Jestli je nekde diskuse, dejte sem prosim odkaz.

Je pravda, ze na internetu je ted kazdy odbornik, publikovat muze kdekdo, kazdy, kdo cuchnul k HTML uz se povazuje za programatora, kdo ma digitalni fotak, uz je umelec atd.

Nektere clanky (i na anglickych odbornych webech) mi ale pripadaji, ze ze sebe clouvek chce udelat znamou osobnost. Asi zacnu taky. Jen najit neco, co muzu opsat :-).

Pavel Lang

Když už je to článek o pěkném kódu obecně, tak by stálo za zmínku, že každý jazyk má množinu konvencí, které by se měly při psaní kódu aplikovat, měly by být konzistentní napříč projektem, či pokud je využívan nějaký framework, tak i na konzistentní s frameworkem.

U Pythonu se mi osvědčilo (hlavně ze začátku) používat UliPad, který má vestavěnou kontrolu na některá pravidla PEP (a mimochodem, podporuje syntax highlighting i pro django šablony, HTML, javascript… a podporuje i (ne sice nejdokonalejší) code-completion, což je třeba u Pythonu docela přínos – určitě doporučuji pro Python alespoň vyzkoušet)

Jinak, kód jednoduchou angličtinou nikoho neurazí a když jo, jak chce potom používat knihovny? Vždy když něco píšu chci, aby to mělo potenciál růstu i za hranicemi a tak se snažím většinu psát anglicky, v djangu píšu anglicky i všechny stringy v pythoním kódu za použití ugettext či  ugettext_lazy as _

Jinak díky za článek, každá snaha o snahu vysvětlit rozdíl mezi programováním a patláním kódu se cení, jen tak dál ;-)

che

V C/C++ (a mj. i PHP) se dá s úspěchem použít Doxygen.

Tupčík

Jistě, zásady popsané v článku jsou nejzákladnější základ. Momentálně v souvislosti s psaním Clean Code řeším problém, který ale nikde moc pospaný není.

Máme veškerý kód psaný podle všech možných zásad, každá metoda/třída/member je zdokumentovaná. OK. Zdálo by se, že kdokoli ke zdroji sedne, všechno hned ví. Jenže to tak vůbec není.

Ukazuje se, že u většího systému chybí popis z většího odstupu. Komentář ke každé metodě mi příliš nepomůže zjistit, jak jsou vlastně provázány větší celky, jaký je mezi nimi mechanismus, na jakých konceptech aplikace stojí. Jak a kde ale dokumentovat tohle?

Je možné, že problémem je chybný návrh, že i tyhle větší celky by měly být zachyceny pomocí high-level rozhraní nebo tak něčeho, co by se pak zdokumentovalo jako ostatní kód, těžko říct. Právě teď to ale cítím jako problém.

František Kučera

Např. v Javě jde komentovat balíčky tzn. nějaké logické skupiny tříd – ale i to je pořád hodně nízkoúrovňové. Nezbývá než začít psát dokumentaci-příručku pro vývojáře, modely, diagram nasazení, případy užití, další UML… je to dost práce dělat dodatečně (ale pořád míň, než to vysvětlovat každému nováčkovi zvlášť, nebo sám po delší době nevědět, jak je systém postavený)

Pavel Lang

Pro tyto účely může (a často slouží) nějaká varianta wiki

František Kučera

jj, wiki je prostě forma, jak se dá taková dokumentace zveřejnit nebo tvořit. Ale obrázek (diagram, třeba na té wiki) řekne víc než tisíc slov (a nebo taky ne – podle toho, kdo ho dělal).

Tupčík

Samozřejmě, wiki používáme. Jenže to už jsou dvě docela oddělené věci. Nemůžu (nebo neumím) vygenerovat jeden dokumentační balík z kombinace wiki + komentáře ve zdrojácích. Rád bych jednu věc, ne dvě nebo víc. Taky mi není příjemné přepínat mezi wiki nástrojem a nástroji Visual Studia. Dal bych přednost něčemu integrovanému.

Pavel Lang

Tak v jakém jazyku tvoříte, abysme si to ujasnili? Asi se dá pár věcí sešroubovat líp s Javou, svn a pár jiných zase s C#, VisualStudiem… ustící do HTML prezentace v podobném smyslu jako starý Doxygen a C++.

VisualStudio samo o sobě podporuje UML pro třídy (včetně těsné vazby na třídu ve zdrojáku) a myslím, že lze tvořit i UML obecnější, pak už jen zavést nějakou konvenci ve smyslu kde jaká dokumentace bude umístěná…

Pak tady máme už od Knutha a TeXu „literální programování“, které hraničí občas až v extrémy, že zdroják obsahuje 80% dokumentace a 20% kódu.

Pravděpodobně by mohlo být nalezeno řešení, které pěkně zkombinuje jak docstringy, tak i třeba vnořené doc adresáře (se soubory v přátelském textovém formátu, třeba wiki, markdown (viz GitHub), pseudo HTML) v hiearchii zdrojových kódů tak, že by se na základě toho generovaly různé úrovně HTML dokumentace nějakým centrálním serverovým skriptem přímo z repozitáře, možná že by se tak dal udělat nějaký plugin do Mediawiki.

Visual Studio lze také různě rozšiřovat (ty profi verze určitě) i když to už je docela overheat; s Java IDE nemám zkušenosti, ale myslím, že v tomto směru tam bude situace příznivější (ať už NetBeans nebo Eclipse)

Osobně jsem se nedostal do situace, že by mě nestačil zdrojový kód s doc-commenty + někde stranou analýza včetně těch UML srandiček, nejlépe před sebou na papíře…

Ad přepínání – to parádně řeší dva monitory, případně Alt+Tab ;-)

Tupčík

C#. Ujasním to – chci protáhnout projekt (solution) nějakým generátorem dokumentace, výsledkem by měl být HTML balík a CHM. Nedaří se mi do toho začlenit žádné dodatečné dokumenty, nebo ano, ale pak zas ty dokumenty nemají žádné vazby na kód (při refactoringu se nezmění) a nejsou nijak kontrolovány při generování dokumentace.

UML… No snad, i když UML extra moc neoblibuju. Určitě by to částečně pomohlo, asi vyzkouším. Jiná věc je, jestli to UML pak dostanu do výše zmíněné HTML+CHM dokumentace (helpu).

Overhead, zřejmě. Dnes se zrovna moc nepřehřívám.

Alt+Tab, že mne to nenapadlo. Ne, vážně, jde o přepínání mezi dvěma nástroji s různým stylem práce, jejichž data navzájem nejsou nijak provázaná, nereagují na vzájemné změny. Když přejmenuju parametr metody/třídu/metodu ve Visual Studiu, změní se mi název i v docstringu.

Nevíte jestli .NET 4 nějak rozšiřuje funkčnost dokumentačních ta­gů?

Pavel Lang

<cite>Nevíte jestli .NET 4 nějak rozšiřuje funkčnost dokumentačních tagů?</cite>

Ne, to nevím, nepochopil jsem, jak to myslíte, jako jestli se dají přečíst reflexí? Myslím že pořádn nedají. xml dokumentaci pro assembly generuje samotný kompilátor csc, z té by se mělo vycházet pro generování samostatného html (a spíš to splitnout na několik souborů). html se dá potom do chm převést..

ad grafika, no, nevím, jak ty MS UML vyexportovat do nějakého obrázku, ale co jsem většinou potřeboval, tak mi krásně vygeneroval dot/graphviz.

Pak ještě vím, že MS uvolnil MPLEX a MPPG a pomocí nich lze udělat vlastní parser na ten dokumentační text, který vrací tokeny rozlišené už na konkrétní identifikátory, ale nevím, jestli to funguje dohromady s refaktoringem, teoreticky by mohlo a pak, za předpokladu, že byste měl ten svůj dokumentační formát zmáklý, pak by na něm mohl fungovat i refaktoring metod zafungovat a post-build task by mohl sestavit komplet dokumentaci sestavenou ze dvou částí – první by byla ta s explicitních dokumentčních souborů; druhá dokumentované třídy samotné z toho xml od csc

Tupčík

Ne, reflection jsem na mysli neměl. Spíš v tom smyslu, jestli do nich můžu strčit obyčejné HTML nebo tak nějak.

Jde mi vlastně o to, abych mohl udělat obecný dokument v něčem WYSIWYG v prostředí VS a v tom dokumentu se odkazovat na entity z kódu, přičemž odkazy budou brány v potaz při refactoringu. Možná to i jde, jenom já to nevím.

Pavel Lang

Do doc-commentů lze zažadit všechny platné xml značky, některé mají speciální význam, ale xhtml by to asi skousnou mělo, stačí vyzkoušet ;-)

S tím WYSIWYGem to není nemožné, ale je to pracné… je potřeba naimplementovat komplet editor jako add-in… Doporučuju stáhnout odpovídající Visual Studio SDK, tam je pár samplů a možná že někde uvidíte, co obnáší vytvořit něco pro VS, co umí refaktoring…

Doporučil bych projít XML Documentation Comments (C# Programming Guide), tam bude základ jak s commenty pracovat.

Tupčík

Já vám rozumím, ten odkaz, respektive to co je za ním pochopitelně znám, ale já v žádném případě nebudu nic implementovat. Mám beztoho práce až nad hlavu, sháním hotové funkční řešení k okamžitému použití. V každém případě díky za snahu.

Aleš Roubíček

Existuje plugin pro DXCore, který ukazuje v panelu vygenerovanou dokumentaci online při psaní doc-commentů. Oboje je free Viz. http://www.paraesthesia.com/archive/2004/11/15/cr_documentor—the-documentor-plug-in-for-dxcore.aspx

Vkládání dalších HTML souborů do dokumentace umožňuje Sandcastle. Myslím, že by se dal nascriptovat tak, že bude výstup použitelný v nějaké Wiki.

Michal Augustýn

Jojo, jak psali ostatní – chce to nějakej vyšší level dokumentace – např. diagramy nasazení, diagram aktivit, sekvenční diagramy, diagramy komponent a různé další, které jsou pro daný projekt vhodné.

Jak už bylo řečeno výše v komentářích, a já se s tím ztotožňuji, komentovat pedantsky každou metodu a proměnnou vede spíše k nežádoucímu šumu a IMHO je důležitá hlavně tahle hi-level dokumentace.

Tupčík

To zas ne, žádný nežádoucí šum. Jak jinak by se z komentářů dala vygenerovat rozumná dokumentace? Nekomentovaná metoda neexistuje (diskutujme snad jen o privátních).

Martin Mayer

Výbornou dokumentací k tomuto jsou unit a integrační testy.

Tupčík

Kód není dokumentace. Dokumentaci si může přečíst i polo- nebo vůbec-ne-programátor. Dokumentace kódem… no prostě ne.

Oldis

dobrej kod je sam sobe dokumentaci.

iwtu

Z mojich osobnostich skusenosti.
Niekedy je sa dlhsim nazvom lepsie nevyhnut. Skor dat bacha na to, aby neobsahoval zbytocne slovicka. Nazov moze sluzit jednak na identifikaciu, aby som vedel, k comu sa dany event viaze, jednak na rozlisenie podobnych komponentov. Dlhe nazvy netrepa pisat rucne. Vie ich doplnovat aj vim.

Jednopismenkove nazvy. Asi ten priklad nie je navhodnejsi. Snad nie som jediny, komu je na prvy pohlad jasne, co ten kod robi.

Enum a statická analýza kódu

Mám jednu univerzální radu pro začínající programátorty. V učení sice neexistují rychlé zkratky, ovšem tuhle radu můžete snadno začít používat a zrychlit tak tempo učení. Tou tajemnou ingrediencí je statická analýza kódu. Ukážeme si to na příkladu enum.