it-swarm-eu.dev

Je kód s komentářem opravdu vždy špatný?

Prakticky každý text o kvalitě kódu, který jsem četl, souhlasí s tím, že kódovaný komentář je špatná věc. Obvyklým příkladem je, že někdo změnil řádek kódu a nechal tam starý řádek jako komentář, což zřejmě zaměnilo lidi, kteří tento kód později přečetli. To je samozřejmě špatná věc.

Ale často se ocitnu opouštět kódovaný komentář v jiné situaci: píšu výpočetní-geometrii nebo algoritmus zpracování obrazu. Abychom porozuměli tomuto druhu kódu a našli v něm potenciální chyby, je často užitečné zobrazit průběžné výsledky (např. Nakreslit na obrazovku sadu bodů nebo uložit bitmapový soubor). Pohled na tyto hodnoty v debuggeru obvykle znamená dívat se na zeď čísel (souřadnice, hodnoty surových pixelů). Není to moc užitečné. Psát debugger vizualizér pokaždé by bylo nadměrné. Nechci ponechat vizualizační kód v konečném produktu (bolí to výkon a obvykle jen zmatí koncového uživatele), ale také ho nechci ztratit. V C++ mohu použít #ifdef podmíněně kompilovat tento kód, ale nevidím mezi tím velký rozdíl:

/* // Debug Visualization: draw set of found interest points
for (int i=0; i<count; i++)
    DrawBox(pts[i].X, pts[i].Y, 5,5);
*/

a tohle:

#ifdef DEBUG_VISUALIZATION_DRAW_INTEREST_POINTS
for (int i=0; i<count; i++)
    DrawBox(pts[i].X, pts[i].Y, 5,5);
#endif

Většinu času tedy nechávám pouze vizualizační kód, s komentářem, co se vizualizuje. Když jsem si přečetl kód o rok později, jsem obvykle šťastný, že mohu jen zrušit vizualizační kód a doslova „vidět, co se děje“.

Měl bych se z toho cítit špatně? Proč? Existuje vynikající řešení?

Aktualizace: S. Lott se zeptá v komentáři

Jste nějakým způsobem „zobecňujícím“ kódem, který zahrnuje jak ladicí, tak nesmyslný, zastaralý kód? Proč děláte tento příliš zobecněný závěr?

Nedávno jsem četl Roberta Martinse "Clean Code", který říká:

Jen málo praktik je stejně odporných jako kódování komentářů. Nedělejte to !.

Znovu jsem se podíval na odstavec v knize (str. 68), neexistuje kvalifikace, nerozlišuje se mezi různými důvody pro komentování kódu. Tak jsem přemýšlel, jestli je toto pravidlo nadměrné (nebo jestli jsem knihu nepochopil), nebo jestli to, co dělám, je špatná praxe, z nějakého důvodu jsem to nevěděl.

53
nikie

Výhodou # ifdefů oproti jeho komentování je, že (na velkých projektech) můžete mít definice uvedeny v souboru make nebo config - a nemusíte tedy manuálně chodit s nekomentovanými věcmi, sestavovat a pak znovu -kompletujte je, pokud je na mnoha místech. Nevýhodou je, že změna DEFINE projektu bude obvykle znamenat přestavbu celé věci, nejen změněných souborů.

I když ... myslím, že „komentovaný kód je špatná věc“ ve skutečnosti odkazuje na mrtvý kód, který lidé prostě nechtěli smazat z jakéhokoli důvodu (strach z odhazování něčeho, co utratili) možná čas?). Není to opravdu o situaci, kterou pro vás jde.

58
TZHX

Pokud je to komentováno, pak se může hnilo: když se najednou rozhodnete, že to budete potřebovat znovu, uvědomíte si, že se již nezkompiluje, nebo není třeba přepisovat, aby vyhovoval ostatním věcem, které se mezitím změnily.

Pokud kód ponecháte, ale takovým způsobem, že jej kompilátor může optimalizovat pryč, není-li to nutné, budete mít prospěch z udržování aktuálního kódu a nemusíte trpět přidaným binárním kódem velikost nebo běhový výkon.

Například u C hrozí hniloba:

/*
doSomeDebugStuff();
*/

A tak je to:

#if 0
doSomeDebugStuff();
#endif

Ale to je dobré, protože je vždy zkontrolována platnost kompilátorem, ale pravděpodobně bude optimalizována pryč:

if (0)
{
  doSomeDebugStuff();
}

Edit: jak poukazují ostatní, používejte spíše smysluplný symbol než 0 pro test je ještě lepší.

25
Graham Borland
// The problem with commented out code is that it can hide what you're actually
// trying to say in a wall of text.  Syntax highlighting may help, but you're 
// still left with this huge ginormous wall of text in front of you, searching
// through it for what the actual answer is. You'd think that mentally it'd be 
// really easy to disregard the comments, but in actual usage, it's a lot harder
// than a one Word answer that can tell you what you're looking for. It's tough.
/* Sometimes they'll even through you off with different comments. */ Yes.
// It's really tough to deal with people that don't like to use source control, 
// that would rather comment lines and lines of code instead of deleting the 
// code and checking in revision.  Cue irrelevant paragraph about the reason why 
// I wrote this instead of just deleting the entire block and replacing it 
// with my intention. Maybe I was hedging my bets? Cue misspelled wrod.  
18
George Stocker

Myslím, že je třeba rozlišovat mezi komentovaným kódem, který je zastaralý, a kódem, který se používá pouze v sestavení ladění (nebo jiném „speciálním“ sestavení, podmíněně kompilovaném). Ten je běžnou praxí a nic s tím není v pořádku.

První by neměl být přítomen ve zdrojové základně, protože systém pro správu verzí sleduje zastaralé věci, pokud byste ho někdy chtěli získat zpět.

15
Alex Budovski

V kódování není téměř „vždy“ :) Pokud víte dost o důvodech pokynů a máte opravdu dobrý důvod pro jejich porušení, udělejte to.

Například komentuji kód, když dělám „kamikaze-refactoring“ a potřebuji vizuální připomenutí, abych přidal věci zpět nebo si vzpomněl, jak starý kód chvíli pracoval. V takovýchto případech je rozhodující, abyste smazali komentáře později, ale jinak jednoduše zaplní váš kód.

11
Homde

Někdy vložíte do komentářů kód, abyste zobrazili jak používat třída - to se velmi liší od kódu, který se použil ke spuštění.

8
Ian

Dělám spoustu kontrol kódu a zjistil jsem, že neexistuje žádný skutečný důvod pro komentář kód bez ohledu na důvod. Pokud používáte kódovaný kód pro účely ladění, můžete vytvořit mechanismus trasování, který je zakázán v režimu vydání nebo má úrovně trasování (vždy dobré, aby bylo možné sledovat verzi verze), nebo můžete jednoduše použít ladicí program.

Komentovaný kód je špatný, protože když si ostatní čtou kód - zejména když jste zdůrazněni, že se snažíte opravit chybu, když je původní autor na dovolené - je to velmi matoucí číst kód, zejména pokud je chyba způsobena nesprávně umístěn // na začátku řádku ... i pomocí/* můžete náhodou komentovat něco, co by tam mělo být - nebo ne.

Chcete-li udržet svůj kód čistý a čitelnější, odeberte kód s komentáři, jeho již obtížně čitelné programy, jako je to bez nutnosti číst kód, který může nebo nemusí být významný.

3
AndersK

Ano to je.

I když máte ladicí kód, který ve své produkční verzi nechcete, neměli byste jej komentovat. Použitím #ifdef 's je lepší, protože pak můžete ladění snadno zapnout a vypnout pomocí #define makro nebo pomocí samostatné konfigurace sestavení. To rozhodně trápí nutnost jít do kódu a komentovat/rušit každý blok debugovacího kódu ručně.

A pokud potřebujete mít flexibilitu, abyste zapnuli některé ladicí bloky, ale ne jiné, měli byste seskupit ladicí bloky do "ladících úrovní".

Lepším řešením by bylo nepoužívat vůbec předprocesor a používat funkce nativního jazyka, jako jsou konstanty a příkazy if. Takže místo

#define DEBUG0
#ifdef DEBUG0
  // debugging code
#endif

můžeš mít

const bool DEBUG0 = true;
if(DEBUG0)
{
  // debugging code
}

Výhodou tohoto postupu oproti použití předprocesoru je to, že váš ladicí kód bude vždy zkontrolován kompilátorem. Tím se snižuje pravděpodobnost, že se hnilo, když změníte kód kolem něj.

Nebudete trpět žádným výkonným zásahem, pokud uděláte logickou vlajku nepravdivou, protože moderní kompilátory optimalizují pryč nedosažitelný kód. V nejhorším případě byste mohli dostat varování kompilátoru o tom.

2
Dima

Nemyslím si, že to, co děláte, je špatné a špatné, ale myslím, že byste měli mít alespoň nějaké skutečné komentáře s vysvětlením toho, co dělá, proč a jak a kdy použít to.

Osobně bych normálně vložil tento druh do nějakého druhu IF DebugMode = TRUE typ úsilí kolem daného kódu a nastavit to jako příkazový řádek/počáteční parametr. Pro mě je to snazší vidět, že proto kód existuje a jak jej nastavit, i když ve vašem případě může dojít k problémům s výkonem i s tak malým porovnáním, kterému se chcete vyhnout.

Takže bych asi viděl, co děláte, jako nezbytné zlo, spíše než ven a ven špatně. Pokud najdete nějaký způsob, jak to zefektivnit, pak to zjevně udělejte, ale já bych o tom nepřekonal.

1
Jon Hopkins

Myslím, že jedním z důvodů, proč byl kód vyřazen, je považován za zápach kódu, je to, že to naznačuje, že programátor, který ho tam umístil, nerozumí jejich ovládání zdroje nebo že žádné nepoužívá. Každý z nich vrhá další pochybnosti na spoustu dalších věcí, které také dělají.

Máte-li k tomu legitimní důvod a, necháte vysvětlení, proč je legitimním důvodem, kde jej lze nalézt, pravděpodobně se vám daří dobře. Většina věcí, které jsou obecně považovány za špatné zprávy, může být také užitečným nástrojem v pravých rukou. Problém je v tom, že ty ruce jsou vzácnější než lidé, kteří si myslí, že je mají.

0
glenatron

Pomáhá poskytnout historii toho, jak mysl programátorů v té době fungovala. Ale v těchto dnech všudypřítomné kontroly zdroje není důvod nechat ji v konečném řezu - předchozí verze budou obsahovat starší kód, pokud byste se na něj někdy měli odkazovat.

0
5arx

Nemyslím si, že jsou zde absolutní věci. Někdy zanechám komentářový kód, když je to jen malý úryvek, zejména, pokud existuje rozumná šance, že jej brzy znovu odkomentuji. V zásadě tyto úryvky nechávám, dokud nenarušují čitelnost skutečného kódu a pokud se všude ne multiplikují.

To, co naprosto odmítám, jsou úplné metody komentovaného kódu. Ano, už jsem je viděl: WTF. Mohou odpočívat v nebi s revizí zdroje ;-)

0
Andres F.