K technicke dokumentaci mi prijde zajimave tohle (jako system premysleni, co clovek pise pro koho):

Diátaxis
https://diataxis.fr/

Beru argument, ze komentar zastara a muze programatora svest na scesti, ktere skonci chybou. Ale trochu tady predpokladame, ze ten programator vsem komentarum 100% veri a necha se na to zcesti svest. Pokud se to stane, troufnu si rict, ze to je dost casto v codebase co je tak jako tak komplikovana a je slusna sance, ze udelam spatne rozhodnuti i na zaklade cteni kodu. V realu v legacy kodu rad vyuziju coby signaly vlastni cteni kodu, dostupne komentare i treba LLM. A i potom pocitam s tim, ze napr. oprava nejakeho tricky edge casu muze rozbit zas jine veci, o kterych jsem ani nemel tuseni a samozrejme na ne nejsou testy.

Sam jsem priznivce toho v prvni rade veci dobre pojmenovavat. Kdyz jsem se ale onehda s praci setkal s kolegyni, co hodne cetla Uncla Boba a kazdy znak komentare pro ni byl nepritel tak to uplne moc pozitivni zkusenost nebyla. A pokud z nejakeho hodne konkretniho dobreho duvodu delam v kodu neco co se na prvni pohled zda naprosto nelogicke tak je podle me napsani komentare vzdycky na miste. Nicmene vetsina lidi co jsem za svou karieru potkal byla spis lina komentare a obecne jakykoliv detailnejsi dokumentace psat.

JANFROG: Chtěl bych vidět někoho, kdo zvládne programovat v Assembly bez komentářů :-D

Jinak tady na ty diskuzi je pekne videt, jak je ten nazor determinovanej predchozi zkusenosti. Ted budu teoretizovat: ta zkusenost je dana hlavne dvema vecmi (i) pracovnim prostredim (kolegove a vztahy, nastavenim a funcknosti procesu) a (ii) typem projektu (web aplikace je jinej sport nez data processing a jeste jinej sport jsou (jit) prekladace nebo firmware).

Co by bylo (pro me) zajimavy videt je jestli panuje vetsi shoda v ramci tech "subkultur" (webaru, databazistu, systemaku). No nic, konec sneni, cas jit neco delat :-)

AXTHEB: S pristupem, ze existuje jedine spravne reseni (design projektu) a cokoliv jineho je spatne jsem se setkal. Malokdy ale u 40+. Mas predsudky a nejsou spravne.

Ten slozity format specku ma-ISO normu. Jmenuje se C++ a cist standard je pro valnou vetsinu veci ten nejhorsi zpusob zkoumani jak to funguje.

Vynucovat 1:1 pojmenovani prvku abstrakce proti nejakemu teoretickemu modelu znemoznuje mit kdy abstrakci popisujici cokoliv obecnejsiho nez presne ty entity ktere ten jeden dany model obsahuje. Takze nemit to tak udelane naopak dava perfektni smysl.

QWWERTY: Chápu, je lepší mít jednu nohu než žádnou.

AXTHEB: oh sweet summer child... mimo profesni sw development vypada napr. u nas situace tak, ze:
- kolega radsi vsechno testuje manualne, nez aby vzal kus logu a napsal si test case. naprostou vetsinu lidi, co u nas pisou skripty, se mi nepovedlo presvedcit, ze testy jim usnadni zivot, i kdyz to znamena psat vic kodu. a to i pres to, ze tam maji treba X zanorenych podminek, takze manualni pretestovani je pain
- kolega napsal funkcni script na automaticky troubleshooting. fakt uzitecny tool. a je to ten stejny clovek, co hledal 20 minut, jak vypnout output na stdout, ackoliv o 3 radky niz mel print("")... konverzace vypadala jako "ono se to tam nekde vypisuje". "ok, ukaz mi, ktery radek kodu se spusti, kdyz se to vypise". "no to ja nevim"
- dalsi kolega mi rekl, ze nepise ani komentare, protoze nema dobrou anglictinu a nema mentalni kapacitu na psani komentare, aby v EN daval smysl. kdyz jsem mu rikal, at je pise CZ/SK, protoze lepsi neco nez nic, tak vypadal ochotnejsi zacit aspon uvazovat o jejich psani

a protoze nejsme devs, tak programovani nemame v popisu prace => kvalita kodu se neda pouzit jako metrika pro osobni hodnoceni
aktualne beru kazdy komentar, ktery nekdo nekdy nekam napise. i kdyby byl outdated, tak aspon napovi, co se tam ten clovek snazil delat


moje jedina nadeje je, ze se nas ted snazi zapojit do vetsiho externiho projektu a ten uz ma dopredu nastaveny standardy, takze kdo se zapoji, tak je bude muset dodrzovat

OMNISLASH: myslim ze tihle pro nas delali jako kontraktori. Odevzdali kod uplne nahovno, rozbili co slo ale argumentovali tim, ze naprogramovali presne to co sme zadali a ty veci okolo rozbili de facto schvalne, aby jim jejich kod nejak fungoval. I kdyz nefungoval dobre. A pak se jeden jejich tester hlasil k nam do firmy a hrde poukazoval na to, ze ten kod testoval on

Ja mam teda s komentarema asi dost jinou zkusenost nez vetsina… prijdou mi k nezaplaceni.

Napr. se parsuje syntakticky velmi slozity vstup-mit nad funkci parseFoo popsany format Foo a jeste treba malou ukazku je imo super.

Podobne kdyz je nejaka specka a ted je to implementovano jako par stovek trid, tak mit tak nejak lidsky napsano jakou entitu ze specky trida s podobnym ale ne uplne stejnym nazvem modeluje je zase k nezaplaceni.

Podobne u slozitejsich algoritmu-proste si precist, ze hledame connected components v grafu a stavime z nich jiny graf a jeste jsme prisli na genialni optimalizaci ktera nam zadarmo prekvapive zajisti nejakou vlastnost toho novyho grafu je proste 100x lepsi nez se dozvedet, ze deklarujeme worklist a vrhneme ho do 100-radkovy bohate vetveny smycky…

RUDOLF: U nas ma kazdy package svoji dokumentaci, ktera se meni s kodem, nebo alespon by se mela. Dokumentace celeho produktu se pak builduje z tech partial dokumentaci. Pri buildu se validujou vsechny relativni linky.

AXTHEB: Osobně jsem si jednu dobu myslel něco obdobného, ale změnil jsem názor. Vhodný komentář na příhodném místě může ušetřit spousty času při hledání chyb.