Zlepšení čitelnosti vlastního kódu

[xyz]

Jeste me napadla takova vec. Kdysi kdesi jsem cetl neco jako "kod by se mel umet cist jako anglicky text".
Od te doby se snazim psat kod takovym stylem a pokud se podivat na kod stary jakkoliv dlouho, okamzite vim, co to dela.
Napriklad neco jako toto... pricemz logovani jsou pro me zaroven komenty.

Kód: [Vybrat]

if (device.Type == "android") {
     logInfo("Main process for " + device.Name + " started")
     var unprocessedData = downloadDataFrom(device)
     logInfo("Unprocessed data with length of  " + unprocessedData.length + " rows downloaded")
     var processedData = processData(unprocessedData)
     logInfo("Data processed with length of  " + unprocessedData.length + ". Ready for saving to database")
     var saveResult = saveDataToDatabase(processedData)
     logInfo("Main process for " + device.Name + " ended with result: " + saveResult)
}


Trochu si rypnu. Ten if (device.Type == "android")  je stoprocentne pouze na jednom miste v programu :-)

[Reklama]

[nullpainter]

Tak předně, nepovažuji se za programátora, ale spíš za přeplaceného elitního prasiče.

Ani nepřekvapují komentáře kolegů, které v průběhu let prostě občas přijdou:

Číst po tobě kód je jako strkat si do zadku zahradního trpaslíka.

nebo

Tohle mám číst? Kdybys mě vzal cihlou po hlavě, bylo by to milosrdnější!

a nejnovější

Tohle jsi dělal ty nebo to je výstup obfuskátoru?

Ten poslední komentář se mě vlastně dotknul... 

Máte nějakou rozumnou knížku, ze které i prasič pochopí, jak psát čitelněji?

Což mě přivádí k pár věcem:

• Jak zlepšit čitelnost vlastního kódu?
• Jak psát tak, abyste se chytli i po dvou letech?
• Máte oblíbené "krásné" zdrojáky, jejichž čtení vám přivodí extázi a snažíte se psát podobně?

EDIT: A abych přišel s trochou do mlýna, tyto konvence vesměs dodržuji:
https://github.com/ktaranov/naming-convention/blob/master/C%23%20Coding%20Standards%20and%20Naming%20Conventions.md

Tvůj problém je zjistit co se blbě čte či chápe cizím:

- Zeptej se co jim vadí.
- Přečti si po sobě nějaký kód cos psal a který už nemáš v hlavě. Co luštíš?
- Pozor na to co ti říkají že jim vadí. Ze zkušenosti kodéři vytýkají především triviality (závorky, mezery ...) a uchází jim podstatný chyby (leak paměti ...). Setkal jsem se i s tím že mi vytkli že je něco prasárna a až to pak používali tak přišli že to je super - to chápu tak že občas "prasárna = něco co nechápu".

Knížky bych nečet, akorát ti daj do hlavy problémy který nemáš ty ale měl autor. A některý radej pitchoviny (Clean Code je o tom psát milión malých funkcí -> totální špagety kód)

[premekv]

Jeste me napadla takova vec. Kdysi kdesi jsem cetl neco jako "kod by se mel umet cist jako anglicky text".
Od te doby se snazim psat kod takovym stylem a pokud se podivat na kod stary jakkoliv dlouho, okamzite vim, co to dela.
Napriklad neco jako toto... pricemz logovani jsou pro me zaroven komenty.

Kód: [Vybrat]

if (device.Type == "android") {
     logInfo("Main process for " + device.Name + " started")
     var unprocessedData = downloadDataFrom(device)
     logInfo("Unprocessed data with length of  " + unprocessedData.length + " rows downloaded")
     var processedData = processData(unprocessedData)
     logInfo("Data processed with length of  " + unprocessedData.length + ". Ready for saving to database")
     var saveResult = saveDataToDatabase(processedData)
     logInfo("Main process for " + device.Name + " ended with result: " + saveResult)
}


Podepisuju, myslím, že to bylo v pragmatic programmer? a z té knížky jsem si odnesl zejména toto.

Pro mne jsou tedy základ jsou menší třídy/metody s výstižným pojmenováním (byť někdy delším), nemíchat "granularitu" (jako to má kolega výše, metoda říká provedou se kroky A, B, C a detaily těch kroků v dalších "low level" metodách - ty jsou definované níže po této "high level" metodě, aby se kód četl "seshora dolu").

Dále: komentáře považuji za přeceňované. Když cítím potřebu psát komentář, zkusím se zamyslet nad tím, jestli se kód nedá nějak zlepšit (a nebo testy přidat/zlepšit), aby ten komentář nebyl potřeba.  Ideálně by měla jít funkčnost vyčíst z kódu a z testů (ty by měly dokumentovat, co od kódu čekám a jak reaguje na různé vstupy ). Velmi často pomůže rozdrobení kódu do menších celků a přepis viz odstavec výše. Hodně nepříjemnou vlastností komentářů je totiž to, že zastarávají. Není nic "lepšího" než číst komentář a vidět, že kód (už) dělá očividně něco úplně jiného než je v tom komentáři.

Dále: v zájmu zachování čitelnosti kódu je potřeba někdy spolknout inovativní slinu a "nesnažit se být moc chytrý". Jednak (zne)užití konstruktů jazyka Např. lambda streams - někdy to dramaticky zkrátí a zčitelní kód, ale někdy vidím až příliš  komplexní konstrukce, které by šly přepsat do lidsky čitelnější podoby (i když ten funkcionální zápis je krásný a "co na tom nechápeš"); dále advanced věci (různé binární operace atd.) a zápisy využívajících okrajové vlsatnosti nebo internality jazyka (ano, koukám na vás javascriptaři! Kolega, nebo moje já za rok, spíš ocení třeba delší a "primitivnější", ale čitelnější kód.

Dále: 80 znaků je archaismus, ale občas to řádky zalomit chce (mluvím k sobě, mám máslo na hlavě, kolega řešící diff nějakého mého kódu mi za to nedávno nedával...)

[sudoguy]

Naštěstí pro mě, když se ke svému kódu vracím, tak se velmi rychle zorientuji v tom co dělá. Kolegové si mi nikdy nestěžovali, naopak mám i zpětnou vazbu, že můj kód se čte příjemně. Uvedu za sebe pár tipů co mě teď napadají z hlavy a není to na slohovou práci.

1. Proměnné vždy nějak výstižně pojmenovat i když to může být dlouhé. Včetně dočasných proměnných ve foreach loopech apod.

To už tu sice padlo, ale chtěl jsem zdůraznit že je třeba je používat opravdu všude. Vždycky miluju, když prolítávám něčí vesměs čitelný kód a vidím tam pak něco takového (viz. příklad). Místo toho abys to prolítl, tak pak vyšetřuješ co tam asi tak může být.

Špatně:

Kód: [Vybrat]

foreach($values as $k => $v){
Lépe:

Kód: [Vybrat]

foreach($persons as $name => $age){
2. Komentáře
Shrnující - Aby člověk pochopil co kód dělá bez toho aniž by ho vůbec četl. U větších projektů k nezaplacení - jdeš prostě po komentářích a neluštíš nic. Čteš to jako knihu .
Technické - komentáře k fungování samotného kódu.

Příklad (všimni si, že vůbec nepotřebuješ vidět kód a vidíš co se děje):

Kód: [Vybrat]

# assign variables
...
.
$data = json_decode($_POST['data'],true); # true - get json string into array not object (technicky komentar k prepinaci, aby si nemusel listovat dokumentaci a zjistovat co to dela)
.
...

# verify input
...
.
.
...

# errors detected - return 400 bad request
...
.
.
...

# no errors - put values into DB, return 200 ok
...
.
.
...


[Petr Jahoda]

Jeste me napadla takova vec. Kdysi kdesi jsem cetl neco jako "kod by se mel umet cist jako anglicky text".
Od te doby se snazim psat kod takovym stylem a pokud se podivat na kod stary jakkoliv dlouho, okamzite vim, co to dela.
Napriklad neco jako toto... pricemz logovani jsou pro me zaroven komenty.

Kód: [Vybrat]

if (device.Type == "android") {
     logInfo("Main process for " + device.Name + " started")
     var unprocessedData = downloadDataFrom(device)
     logInfo("Unprocessed data with length of  " + unprocessedData.length + " rows downloaded")
     var processedData = processData(unprocessedData)
     logInfo("Data processed with length of  " + unprocessedData.length + ". Ready for saving to database")
     var saveResult = saveDataToDatabase(processedData)
     logInfo("Main process for " + device.Name + " ended with result: " + saveResult)
}


Trochu si rypnu. Ten if (device.Type == "android")  je stoprocentne pouze na jednom miste v programu :-)

To jsem si vymyslel za chodu, to neni z zadneho programu. Normalne by byl android nejaky enum, ale pro citelnost teto kratke ukazky jsem tam nechal "android" aby jakoze bylo jasne, co se oproti cemu kontroluje.

[Reklama]

[technomaniak]

Hele, když otevřeš s časovým odstupem (rok, dva) nějaký svůj zdroják, tak ti připadá jasný, srozumitelný a čitelný? Že se na něj podíváš a hned řekneš "jasně, to je tak a tak"?

No...pokud má člověk čas si s tím hrát, tak ano.
Ale často se dělají úpravy ve spěchu nebo člověk vymyslí řešení, které s odstupem let není tak jasné

No myslím, si že L to myslel tak že jestli se v tom zdrojáku zorientuješ např. okamžite, po 10 sekundách, 1 minutě, po 1 hodině či déle.  Já např. mám zkušenost, že doba zorientování je závislá na době co jsem ten zdroják neviděl. Čím starší zdroják tím déle mi trvá než se v něm zorientuji.

Ale to nemění nic na faktu, že mám pomocnou dokumentaci (txt,doc,pdf) k projektu nebo zdrojáku, uvnitř komentáře popisující lokální části kódu,  apod..

Ale nejdůležitější u popisu je hlavně to umět vůbec vyjádřit. Mě se osvědčilo to popisovat co nejstupidněji, pokud možno vyhýbat se odborným termínům(protože se jejich význam v čase může měnit) tak aby to pochopilo i malé dítě nebo debil. I za cenu toho, že popis či komentář bude větší.

[Lukas1500]

Užitečný komentář

$pomx = $i; //prirazeni indexu do pomocne promenne X

[Ink]

Užitečný komentář

$pomx = $i; //prirazeni indexu do pomocne promenne X

Tak ono ten příklad kolegy výše (no offense) je trochu podobný:

Kód: [Vybrat]

$data = json_decode($_POST['data'],true); # true - get json string into array not object
Napřed si vymyslím identifikátor, který nic neříká ($data) a pak ještě vysvětluju, jaký význam má true ve 2. parametru funkce json_decode()...

[Pixe]

Pokud v komentáři popisuju kód, je to špatně a prasácky napsané. Je třeba ho psát způsobem, aby byl self-explaining (pojmenování, jednotná úroveň abstrakce napříč metodou,...).

Nemá smysl komentovat "jak" a "co", ale pokud je to nutné, hodí se budoucímu čtenáři vysvětlit "proč" - komunikovat záměr.

Spoléhat se na pomocnou dokumentaci někde v texťáku, confluence, pdfku... Hodně štěstí  Reálně ji ale nikdo neudržuje. To samé platí pro komentáře - lepší žádný komentář, než starý/zavádějící komentář.

[Jiří Havel]

Pro mne jsou tedy základ jsou menší třídy/metody s výstižným pojmenováním (byť někdy delším), nemíchat "granularitu" (jako to má kolega výše, metoda říká provedou se kroky A, B, C a detaily těch kroků v dalších "low level" metodách - ty jsou definované níže po této "high level" metodě, aby se kód četl "seshora dolu").

Tady bacha, je třeba se zastavit na granularitě, kdy ty low level metody dávají smysl samy o sobě. Pokud se řeže dál, tak to sice jde, ale ty metody jsou silně provázané mezi sebou. Jemně mleté špagety jsou taky špagety.

[redustin]

Metoda může být klidně použita jen na jednom místě a slouží třeba k vhodnému pojmenování bloku kódu. Navíc se to pak rychleji krokuje při ladění.

[kanoe22]

1) samo vysvetlujuce pomenovanie premennych, metod a tried

2) nepisat sialene dlhe metody (mal som tu cest s kodom kde som refaktoroval metodu dlhu 600 riadkov kodu, opakujem, kodu, nie kodu + komentarov). Takisto nepisat metody ktorych jedinou ulohou je zabalit volanie dvoch inych metod do jedneho riadku, pretoze povodna metoda bola o riadok dlhsia ako XX maximalne dovolenych riadkov. -> ak s tym ma niekto pri review problem, treba si proste dupnut, vyplati sa to, zvysi sa citatelnost, nebude tam milion metod s cudnymi menami (lebo tie dobre a zrozumitelne su uz zabrane) a kod bude kludne o X percent kratsi.

3) Rozumna struktura tried (podobne ako bod 2, najma jeho druha cast, nemat zbytocne kratke/male veci). Na primitivnu aplikaciu typu konzolova kalkulacka ktoru mate urobit v skole nepotrebujete 25tried aby ste ukazali ze poznate OOP koncept. Stacia vam dve, input_parser a calculator ak uz v zadani po vas OOP chcu. Proste naco mi je trieda ktora ma 2 premenne a k tomu dake 4 metody pracujuce s nimi, ktore su sice ako tak spolu logicky zgrupene ked ich stale mozem mat vo vyssej triede a nenarobi to ziaden problem (musia tam pravdaze logicky pasovat, islo mi o to poukazat ze rozbijat veci na mensie za kazdu cenu lebo "potom to je jasnejsie" je od urcitej hlbky struktury kontraproduktivne).

4) Mysliet pri pisani kodu na to ako sa bude testovat (nehovorim nutne o pouziti TDD, ale mat v hlave aspon matnu predstavu o tom ako na to bude napisany unit/integration test je tiez dobre). Na druhu stranu k tomuto, plati bod 3, pricuchol som si ku kodu, kde sa ocividne vyblaznili a skusali rozne sialenosti, rozne moznosti na aplikovanie DI, struktura tak hlboka ze som myslel ze som si nechal vypisat "tree /" (rozbijali vsetko na co najmensie kusky, aj ked to uz davno nedavalo zmysel). Pridanie akehokovlek kodu bolo tak 50% casu pridavanim novej funcionality, 50% casu opravovanie rozbitych testov. Normalne som sa cudoval ze to je schopne vobec bezat.

5) Komentare na komplikovanejsie casti kodu - nemusi vsetko byt v officialnej dokumentacii metody, ani pred kazdou podmienkou/cyklom/... Je skvele ked su komplikovanejsie metody popisane kludne v ramci jednoho dlheho komentara v tele metody, ala:

//offiko dokumentacia, robim (strucne) toto, vraciam toto
//vstupne parametre a ich popis
NejakaTrieda nejakaMetoda(...){
//tu bude ten spominany dlhy koment
//proste nieco co ludsky vysvetli oc tu kraca aj bez potreby studovania a debugovania kodu
//pretoze niekedy kod nejde napisat tak aby bol zrozumitelny na prvy pohlad

sialene_zlozity_kod();
...
return nejakaTrieda;
}

[nehalem]

...

<trolling>Možno sú tvoji kolegovia iba LOPATY ktorým robí trochu zložitejší kód problémy a mýlia si ho so zlým kódom.Čo sa dá čakať od lopat ktoré robia za kilo mesačne a dokonca až 8 hodín denne za takú almužnu. Nelopata robí za 300k 4 hodiny MAX! (viac to aj tak mozog profíka NELOPATY nedáva a musí sa odpočívať, šustaním stredoškoláčok, prechádzkami po svojej súkromnej pláži ktorú ako nelopata si kúpite v pohode za hotové alebo šňupaním kvalitnej koky priamo z Kolumbijskej plantáže) a zložitejší kód si v pohode píše na papier kľudne aj za volantom svojho Bugatti Chiron na semafore keď mu napadne niečo geniálne a to si samozrejme počíta do pracovnej doby. Komentáre sú len pre lopaty, rovnako ako dlhé názvy premenných, profíkovi stačí len "val x" a z kontextu je mu okamžite jasné, čo ten kód robí. S pozdravom JavamanSK</trolling>

[PanVP]

Moc hezký...hezký...
Ale vyřídíme to rychle.
Chceš 55 Euro na hodinu na ŽL?
90% remote. Java? ...pokud máš certifikát z Ajiny, minimum je C1.

[Mudvy]

Já například čerpám z návyků co jsem se naučil při výrobě rozvaděčů. V elektroplánech je celkem jasná logika jak jsou tvořeny a dá se to aplikovat i na archytekturu a tvorbu zdrojového kódu.

V podstatě je to nemíchání jablek a hrušek ale mít smyslově oddělené oblasti aby bylo jasné kam kouknout když něco hledám. Samozřejmě i za cenu větší pracnosti.

Další inspirací pro mě byla práce konstruktéra. Když děláte velké sestavy a často je editujete také si tvoříte malé celky které jse snáze upravují než když to tvoříte jako jednoúrovňový strom. Navíc například Catie vás dost vyškolí co je a není dobrý přístup. Přijdou změny a člověk zjistí jak špatně si to vymyslel.

Další věc co mě hodně pomáhá je IDE. Používám Visual studio 2017 a když si vzpomenu jak jsem psal v pascalu na střední tak je to nesrovnatelný rozdíl. Tehdy jsem ani nechtěl být programátorem a cokoliv napsat bylo jen procházení dokumentací a hledání syntaxe. Dnes je doba zase dál a už vám ide nehází klacky pod nohy, což hodně pomáhá mít uklizený kód.

Další možnost je vžít se do role zákazníka a jít podle toho co dodám něco vyrábět / používat dál. Například v konstrkuci na féra vzít výkresy a jít si to vyrobit. To pak zažijete osvětu toho jak omezenou představu o srozumitelnosti vaší práce máte. Co je však odlišné od konstrukce je to, že výkresama všechno začíná kdežto napsaným zdrojovým kódem práce končí .

Občas na školení používám přirovnání lidského těla k ideální architektůře zdrojového kódu. V lidkém těle také nemáte zaimplementované plíce přes střeva a dolní končetini. Všechno má jasnou funkci, přenos, struktura, data, vstup, výstup apod. A dalo by se říct že je to miliony let laděný systém .

Ostatně moje zkušenosti jsou jen z projektů které byly v rozsahu do 10 000 řádků. Neumím si představit že bych svým stylem spravoval projekty co mají miliony řádků.