„I never comment anything because I'm always trying to make it so the code itself is the comment.“
Arthur Whitney
Z tohoto vždy lezu po zdi. Není nic lepšího než muset opravovat po někom nějaký kód a nevědět, jestli to tam napsal schválně kvůli něčemu co tam nenapsal, nebo je to chyba ... a to všechno kvůli ne-komentářovému náboženství.
Přesně. A pro toho, co to napsal, je přece z toho kódu vždycky naprosto jasné, co to má dělat. Jenže stejně hnusný protipól je zase povinné komentování. To pak člověk přečte komentář a ví jen to, co se už dověděl ze jmen a typů.
Nevím, jaký přístup je ideální. Možná nechat kód chvíli odležet a pak znova ty komentáře pročíst, aby se člověk vyhnul tunelovému vidění.
Jednak povinné komentování vyžadované ad absurdum jsem ve striktní podobě snad nikde nepotkal. A i tak vám nijak nebrání napsat rozumný komentář.
Ale když jsou komentáře zakázané, tak se dřív nebo později dostanete do situace, kdy budete muset napsat kód o kterém víte, že až se na něj po nějaké době bude někdo koukat (klidně vy sám), tak bude jen blbě čumět a říkat si "Do p*** proč?!"
Zakázané komentáře jsem ve striktní podobě taky nikde nepotkal. Ale potkal jsem už dost jak fanatického "samodokumentujícího" kódu, tak hromadu redundantních (obzvlášť doxygen a spol.) komentářů. Je ale pravda, že jakkoliv špatný komentář se dá přinejhorším vždycky smazat, ale vyvěštit z kávové sedliny už je nejde.
... kolik komentářů reálně popisuje ty důvody, proč je v kódu zrovna tohle?
Neřekl jsem, že každý komentář má nějakou závratnou informační hodnotu.
Já nečastěji dávám do komentářů v kódu předpoklady za kterých má kód fungovat správně (pokud potřeba), nebo nějaké obecné předpokládané vlastnosti systému (t. č.) na základě kterých je nějaká funkce nebo nějaký blok napsán tak jak je napsán - obvykle tím chci ušetřit hledání celé koncepce 1/2 systému (při programování jsem tím musel strávit poměrně čas a mělo to zásadní význam). Nebo pokud např. řeším nějakou zapeklitost systém<->framework<->Q&A<->Management a rozhodnu se spáchat nějaký hřích, tak to tam dobře napíšu.
Ono se taky občas stává, že na základě takového komentáře se zjistí, že nějaká 3 roky stará čuňárna z prvního crazy release bug fix už dávno není potřeba, přestože se hezky jmenuje a je jasné jak si pohrává např. s poly nebo entitami .... (z praxe)
21. 7. 2022, 16:57 editováno autorem komentáře
PS: Když nad tím tak přemýšlím, tak udělám průměrně (odhadem) tak 1-2-3 komentáře za celou feature. Na druhou stranu, máme tam desítky (ne-li stovky) features per project ...
Když nad tím tak přemýšlím dál, tak většinou dělám commenty takové, aby byl případně kód jasný co dělá i z Merge Requestu, bez zkoumání dalších zákoutí systému. Takových zásadních míst zas tolik nebývá.
21. 7. 2022, 17:02 editováno autorem komentáře
@Trident Vasco
To pozor jo, já nenapsal že dám koment do Merge Requestu, ale že dělám komenty (v kódu) takové, že i z těch canců kódu v MR jde díky tomu komentu poznat nějaká zajímavá závislost na okolním kódu (bez nutnosti zkoumat okolí MR). To byla úvaha o kritériích co je dobrý koment.
(Celý kontext je o psaní komentářů do kódu - stejně jako to pravidlo na které jsem reagoval na začátku.)
22. 7. 2022, 15:14 editováno autorem komentáře
@Trident Vasco
@Ink
Uvedu příklad: mám feature (nějaká třída), která odněkud tahá data, která sice existují z nějakého důvodu (A), ale také prostě t.č. v aplikaci nepřímo vypovídají o nějaké závislosti nebo procesech v aplikaci (B), tak k tomu kusu kódu poznačím, že předpokad aby tato dala byla k něčemu je že data (B) prostě nesou nějakou nepřímou informaci a pokud je někdo změní, tak to ovlivní fungování feature na které pracuji.
Takže když feature přestane záhadně fungovat, nebo někdo bude hledat v kódu odkaz na data (třeba skrz setter), tak ví proč a jak ta data byla použita. To se vleze na dva tři řádky (120 chars per line) přímo nad nějaký blok. A taky pak i hned může vidět která data nasměrovat místo toho, nebo že už feature data nepotřebuje nebo další upgrade.
Když pak někdo prochází Merge Requestem, tak přesně ví o co jde a pokud něco ví o datech (A) a já ne, tak už ve vchvíli MR může vidět problém nebo MR zarazit ...
To byl smysl toho mého komentáře o MR. Možná jsem to nenapsal nejlíp ...
22. 7. 2022, 15:25 editováno autorem komentáře
To obecně není moc dobrý nápad:
https://blog.codinghorror.com/the-problem-with-code-folding/
Cituju zásadní část:
Folding is used to mask excessive length. The presence of folded code can lull developers into a false sense of what clean code looks like. Under the cover of folding, you can end up writing long, horrible spaghetti code blocks. If the code needs the crutch of folding to look organized, it's bad code.
22. 7. 2022, 10:07 editováno autorem komentáře
Kde to u vás končívá nevím, ale já jsem se s tím za dvanáct let své praxe nesetkal. Za to jsem se, jak jsem psal, setkal se spoustou kódu, který byl rozlámaný na mnoho podfunkcí bez toho, aby to mělo reálný význam kromě fundamentalismu a toho, "že se to tak přece říká", a bylo problém ho nějak spravovat protože byl problém se v tom bludišti vůbec vyznat.
Ono je to jako se vším. Vše musí mít svou míru. Někdy je lepší kód rozsekat, někdy je lepší ho rozčlenit "nadpisy". Ani jedno nelze zavrhovat a přesně tohle je tedy další způsob jak komentáře využít.
Bohužel jsem to zažil a dost lidí ty špagety "miluje". Co se týče rozdělení na funkce, nebudu řešit, co je moc a co je málo - konkrétní příklady, kdy se to nehodí znám - ale funkce by měla mít popisný název a v rozumném IDE nebo editoru se v místě volání v tooltipu zobrazí i dokumentace k ní, takže obecně jsem pro funkce.
> "že se to tak přece říká"
Dělení na funkce má následující výhody:
- pojmenování
- funkce má argumenty, tudíž jsou zdůrazněny přitékající data, závislosti
- funkce pomáhá k symetrii - tzn: budete mít tendenci vytvářet podobné funkce, s podobnou strukturou
- což pomáhá k extrakci duplicit
- funkce se dá vypnout/nahradit - rychle a čistě, to pomáhá k pohodlnému a bezpečnějšímu refactoringu.
22. 7. 2022, 14:01 editováno autorem komentáře
Jo. Ale to nikomu s _existujicim_ systemem nepomuze. Stejne jako prijde opravar a rekne ze je neco rozbity.
Nektere systemy prepsat - no spis napsat znova muze zabrat dekadu za podpory stavajiciho a nekde tyhle vydaje proste neprosadite az do chvile kdy to nejde skalovat
Pokud potrebujete vyresit problem ( a to obcas propadne i k architektovi) musite mit nastroje jak ho resit. Pri komplexite modernich technologii neni vyjimkou kdy mate kolem sebe na stole bordel a monitoru jak v ridicim stredisku NASA. Obcas to vyzaduje i dekompozici a rozlozeni na mensi tym - dle zavaznosti.
Já jsem nakonec zjistil, že mě z druhého monitoru akorát bolí za krkem. Člověk má stejně jenom jedny oči a pokud není potřeba opravdu srovnávat nějaká zobrazená data hned vedle s kódem řádek po řádku, tak jsem tento přístup opustil.
Daleko lepší je dát si minutku a porozumět datům (struktura), najít přesně co je potřeba a pak používat Debugger a sledovat přímo data které tudy lezou. Také řádné psaní oproti testům + Debugger celkem eliminuje potřebu druhé obrazovky, i když ji mám a 2x za týden použiji ...
Dokonce jsem ve většině případů přestal používat i IDE rozdělené na dvě okna. Stejně člověk píše jenom v jednom. Pokud vyloženě neporovnávám nějaký git, tak to nedělám a soustředím se na to co píši a na to, odkud tahám podklady.
Predpokladam pouze v pripade kdy ta umyslna slozitost byla zamerna. Ano zazil jsem takovych lidi vicero. A to u velkych firem. A jeste se verejne vychloubali ze kod zacunaci takovym zpusobem ze maji praci na dalsi rok. Obcas se clovek pozastavi jak umne plytvaji svym talentem na generovani chyb.
Jenomze je spousta lidi kteri zbytecne komplikuji problemy neumyslne. Jedna se o typ inteligentni blbec. Vic akademik nez inzenyr. Dale nechci naznacovat vuci vecnym asakum co bydli u maminky na jiste fakulte :-)
Jsem dalek jakehokoliv titulu, ale povidal kolega co musi ten material ucit v ramci PhD. ze je to dobry ocistec kdyz cte programatorske vyplody studentu. Asi je. Je totiz neuveritelne tolerantni pri code review :-P