Názory k článku
Jak psát hezký kód I

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.

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

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.

Ano, dostal jsem den předem žádost o povolení publikovat a povolil jsem. Nezdá se mi, že by to komentáře nějak kazily.

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

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

ano.

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

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.

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.

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.

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

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.

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.

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.

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.

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)

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.

„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 :-)

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.

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

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.

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í ;)

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.

ty pys radsi anglicky

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.

„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?

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.

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

„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é).

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).

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.

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. :).

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.

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).

„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.

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í)

„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.

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

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

„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.

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.

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?

Č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 .

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ů.

Testy mám v plánu nakousnout ke konci mini seriálu. Já osobně však s testy nemám velký zkušenosti. První aplikaci s testy jsem začal psát někdy před 6ti měsíci, takže si nemyslím, že bych o tom mohl napsat víc, než jen základy. Možná za nějaký dlouhý čas navážu na tento článek a proberu testy hlouběji, pokud to do té doby neudělá za mě někdo jiný.

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

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/

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.

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.

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…“

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?

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

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

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

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ý…

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.

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

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…“

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

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.

Ano, samozřejmě by mělo být správně ( (x%4==0 ) and not ( x%100==0 ) ) or x%400==0. Pro ukázku však není důležité, jestli je algoritmus správný. Nesnažím se poukázat na to, jak vyřešit algoritmus, ale jak psát kód hezky.

Proč jsem použil tuto konstrukci je jednoduché: kód je čitelnější. Ihned vím, co se děje a nemusím se ani na vteřinku zamyslet.

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 

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

from calendar import isleap

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

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

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

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?!“

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.

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!

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 :-).

Přemýšlel jsem, jestli psát ukázky anglicky nebo česky. Já osobně vše píšu anglicky a nedělám výjimky. Ale nakonec jsem se rozhodl pro lepší názornost (když jsme v česku) použít češtinu. Jak však vidím, tak to byla chyba a připravený druhý díl upravím na angličtinu a budu ji používat i v dalších dílech.

Docstringy určitě patří, ale jak si můžete všimnout, tak nepíši celé kódy, ale jen ukázky. Také chci, aby tyto ukázky byly jasné i pro jiné jazyky. Python jsem si pro ukázky vybral, protože ho mám rád. Snad se nepletu, že například v C/C++ žádné docstringy nejsou. :)

Podobně testy. Chci pouze demostrovat příklad, ne řešit celý konkrétní problém.

InfoPanel je starý projekt a rád bych do něj vložil, co umím, ale není bohužel čas. Jinak momentálně programuji v Djangu webové aplikace.

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 ;-)

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

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.

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ý)

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

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).

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.

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 ;-)

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ů?

<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

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.

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.

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.

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.

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).

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

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.

dobrej kod je sam sobe dokumentaci.