Komentář, který toho říká příliš mnoho

V AI-assisted kódu se čím dál častěji setkávám s specifickým typem komentářů. Poznáte je na první pohled:

# Teď používáme dictionary comprehension, jak jsme se domluvili
user_emails = {user.id: user.email for user in users}

# Opravili jsme ten bug s null handlingem
if data and data.get('value'):
    process(data['value'])

Tyto komentáře nevysvětlují kód. Dokumentují konverzaci. A to je problém.

Proč jsou "prompt leak" komentáře code smell

Když komentář popisuje, co jste AI požádali udělat, místo co kód skutečně dělá, vzniká několik problémů:

1. Časová dezorientace

Komentář předpokládá čtenáře, který byl přítomen během vývoje. "Teď používáme..." naznačuje, že někdo viděl předchozí stav. Budoucí maintaineři – včetně vás samotných za rok – ten kontext mít nebudou.

2. Zastaralá dokumentace

Komentáře svázané s promptem zastarávají ve chvíli, kdy se změní requirements. Pokud požadavky evolvují, tyto komentáře aktivně matou čtenáře ohledně účelu kódu.

3. Šum místo signálu

Kvalitní komentáře vysvětlují proč, ne co. Kód už ukazuje co dělá. Komentáře by měly osvětlit záměr, omezení a kontext, které z implementace nejsou patrné.

Test: Pochopil by to Marťan?

Jednoduchá diagnostika: Může se někdo bez znalosti vašeho vývojového procesu v tomto komentáři vyznat?

Špatný komentář:

# Změnili jsme z for-loopy na list comprehension pro efektivitu
results = [transform(x) for x in data]

Dobrý komentář:

# List comprehension je rychlejší pro velké datasety díky optimalizaci interpreteru
results = [transform(x) for x in data]

Dobrá verze vysvětluje proč byl přístup zvolen. To zůstává relevantní i po napsání kódu.

Co VIBe coding skutečně potřebuje

VIBe coding – AI-assisted vývoj, který upřednostňuje rychlost před dokonalostí – má své místo. Rychlost je důležitá. Ale velocity by neměla obětovat maintainability.

Když vám AI asistent navrhne komentář, zeptejte se sami sebe:

• Vysvětluje to proč tento kód existuje?
• Dá to smysl někomu, kdo to bude číst za dva roky?
• Dokumentuje to účel kódu nebo vývojový proces?

Pokud je to to druhé, smažte to. Váš budoucí já vám poděkuje.

Budování lepších AI collaboration návyků

Řešení není přestat používat AI asistenty – jde o lepší review návyky:

1. Čtěte komentáře před jejich přijetím. Přidává komentář hodnotu, nebo jen popisuje chat s AI?

2. Přepište AI-generované komentáře. Ještě lepší – napište vlastní. Vy rozumíte business kontextu, který AI nemá.

3. Stanovte týmové standardy. Pokud podobné komentáře procházejí code review, kvalita vašeho codebase se bude postupně zhoršovat.

4. Používejte self-documenting code. Jasné pojmenování, dobrá struktura a vhodné abstrakce často eliminují potřebu komentářů úplně.

Závěr

Kód se čte mnohem častěji, než se píše. Komentáře dokumentující prompt místo účelu vytvářejí technical debt, která se časem kumuluje. V shonu při shipování je lákavé to přehlížet – ale jde o formu technical debt, která aktivně mate budoucí vývojáře.

Nejlepší codebase vypráví příběh. Komentáře by měly vysvětlovat děj, ne poznámky scenáristy.

Na NameOcean věříme, že skvělé vývojové praktiky přesahují samotný hosting. Ať už vibe-codujete svůj MVP nebo architektujete enterprise systémy, základy čistého, maintainable kódu zůstávají esenciální. Vaše domain je vaše digitální identita – ujistěte se, že kód za ní vás dobře reprezentuje.