Zakomentovaný kód

Někteří programátoři mají tendenci nechávat v kódu zakomentovaný kód. Ať už jsou jejich důvody jakékoliv, v následujícím příspěvku bych chtěl argumentovat, proč toto nedělat a zakomentovaný kód odstraňovat.

Proč odstraňovat zakomentovaný kód?

Z následujících důvodů:

• Ztěžuje čitelnost kódu. Kód je již sám o sobě náročný na čtení. Když k tomu ale přidáte kusy zakomentovaného kódu, tak se situace ještě zhorší. Představte si, že by článek v novinách vypadal takto (převzato odtud). Jak by se vám asi četl? U kódu, který obsahuje zakomentovaný kód si pořád říkáte: Jaký má tento kód smysl? Nechal ho tam programátor omylem, nebo má nějaký význam? Chtěl programátor pouze něco otestovat? Neměl by být kód odkomentovaný? Jedná se o zbytečné rozptylování, které čtení kódu ztěžuje.
• Kód působí nedokončeně. Když člověk vidí kód obsahující zakomentovaný kód, tak je v nejistotě, zda je kód dokončený. Během svého působení na fakultě jsem se často setkával s tím, že studenti nechávali v odevzdaných zdrojácích zakomentovaný kód. Jak by na vás působilo, kdybyste si koupili skříň, na které by byly viditelné rysy tužkou, které tam nechal stolař?
• Postupem času hnije/zastarává. Nepříjemnou skutečností je, že zakomentovaný kód se typicky nepřekládá a nespouští. Čím více se mění okolní kód, tím více má zakomentovaný kód tendenci zastarávat. Překladač vás totiž neupozorní, že jste zapomněli změnit název proměnné v zakomentovaném kódu (i když třeba použijete IDE, protože to komentáře ignoruje). Když se na zakomentovaný kód podívá někdo později, tak už vůbec nemusí dávat smysl, protože používané proměnné/funkce/třídy z kódu již dávno vymizely. Dá se říct, že zakomentovaný kód postupem času hnije. Což nás přivádí k dalšímu bodu.
• Efekt rozbitého okna. Možná jste o tomto efektu, který bývá zmiňován i v souvislosti s vývojem SW, již slyšeli. Jde o to, že když v kódu uděláte něco špatného (tedy rozbijete okno u domu), pak se zvyšuje pravděpodobnost, že další člověk, který bude kód upravovat po vás, udělá taktéž něco špatného (nasprejuje něco na zeď domu). Když dotyčný uvidí zakomentovaný kód, tak na něj nebude kód jako celek působit úhledně a tak si např. nedá práci s tím vymyslet vhodné pojmenování pro novou proměnnou. A tak to jde dále. Výsledkem je postupná degenerace kódu.
• Nepochopení významu komentářů. Komentář slouží k tomu, aby objasnil kód. Co asi tak objasňuje zakomentovaný kód? Dá se říct, že význam zakomentovaného kódu je dokonce právě opačný, než jaký by komentář měl mít! Používejme komentáře na to, k čemu jsou určeny. Na zablokování části kódu před spuštěním existují jiné nástroje/principy. Pokud např. potřebujete část kódu spouštět jen v ladicích buildech, nedávejte tento kód do komentáře.
• Nepochopení významu systému pro správu verzí (svn, git apod.). Systém pro správu verzí je určen k tomu, abyste se mohli v historii vrátit k předchozí verzi. Potřebujete vědět, jak vypadal kód dříve? Použijte k tomu nástroje z vašeho systému pro správu verzí. Potřebujte vrátit kód z některé předchozí verze? Použijte revert (např. git revert). Potřebujete si něco vyzkoušet? Vytvořte si k tomu novou větev. Potřebujete upozornit na změnu? Napište k ní vhodný commit message. Ten, kdo bude zjišťovat, kdo konkrétní kód napsal (např. pomocí git blame) vám za to poděkuje. Myslíte si, že bude kód využitelný v budoucnu? Dejte ho do samostatné větve/adresáře a původní kód odstraňte.
• Nedocenění testů. Testy, především pak jednotkové (unit) testy, se výborně hodí ke specifikaci toho, jak by se kód měl chovat. Pokud se bojíte, že by někdo váš kód mohl upravit tak, že by nefungoval, napište k němu testy. Ty pak ověří, že kód stále funguje tak, jak byl zamýšlen. Tedy místo toho, abyste psali komentář typu "Následující kód nefunguje: [spoustu zakomentovaného kódu]", napište k vašemu kódu test, který toto ověří. Ten, kdo by se pokoušel kód změnit tak, že přestane fungovat, by narazil, protože by mu spadl test. Že ještě jednotkové testy nepoužíváte? Určitě na ně mrkněte. Jsou velmi užitečné. Lze na nich např. názorně demonstrovat, jak váš kód používat. Navíc, tím, že jsou jednotkové testy kódem, tak dochází při překladu a spuštění k ověření, že příklady využití vašeho kódu stále fungují, což se o příkladech v komentářích říct nedá.
• Ztížené vyhledávání. Když pracujete na rozsáhlém projektu, tak se hodí používat vyhledávání (grep či find na Linuxu). Pokud ale kód obsahuje velké množství zakomentovaného kódu, tak mimo aktuální kód dostanete ve výsledcích vyhledávání i mnoho odkazů na zakomentovaný kód. Tento balast vás pak zbytečně zdržuje, protože se jím musíte prokousat.
• Problémy při mergování/diffování. V neposlední řadě může zakomentovaný kód způsobit problémy při mergování či nepřesnosti při diffování. Jedná se totiž o zbytečný balast, který vypadá jako kód. Důvody jsou pak podobné, jako u odstraňování nadbytečných bílých znaků z konců řádků.

Výjimky

Samozřejmě, najdou se i výjimky:

• Kód v komentářích. Kód v komentářích není zakomentovaný kód. Pokud píšete komentář, tak je naprosto v pořádku do něj umístit ukázky kódu/pseudokódu jako součást vysvětlení. Přeci jen, příklad mnohdy vydá za tisíce slov.
• Zakomentování během vývoje. Když na něčem pracujete a něco měníte, tak si kód ve své lokální větvi klidně zakomentujte. Při zveřejnění vaší práce (např. merge do hlavní vývojové větve) ale nezapomeňte tyto relikty odstranit.

Další čtení

• The danger of commenting out code
• Kill the zombies in your code
• Clean up old commented out code
• C#: I hate commented out code
• Do you leave historical code commented out in classes that you update?
• Checking in of "commented out" code
• Commenting code that is removed?
• Old code in comments
• Is it bad practice to leave commented-out code in production releases?
• Is commented out code really always bad?
• Can commented-out code be valuable documentation?