Skriv bättre kodkommentarer

Bra kommentarer bevarar information som koden inte själv visar tydligt. De förklarar varför ett beslut finns, vilka regler som måste hållas, vilket externt system som kräver ett visst beteende eller hur svåra specialfall ska hanteras. De behöver inte beskriva varje rad kod.

Tre versioner av samma idé

Onödigt:

// Öka attempts med 1.
attempts++;

Det beskriver bara syntaxen. Ett tydligare variabel- eller metodnamn hade varit mer användbart.

Bättre:

// Fjärrtjänsten nekar retries när leaset har gått ut.
if (leaseMillisecondsRemaining > retryDelayMilliseconds)
    ScheduleRetry();

Nu får läsaren en anledning, men bara om påståendet om leaset faktiskt stämmer.

Bäst för en viktig regel:

// Inventory-ID kommer från servern; skapa inte nya ID vid återanslutning.
// Samma ID förhindrar dubbletter om meddelandet kommer flera gånger.
MergeServerInventory(snapshot);

Det är en viktig regel som inte framgår direkt av metodanropet. Testerna kan sedan kontrollera att regeln bevaras.

När behövs ingen kommentar?

• Välj tydliga namn i stället för att förklara otydliga förkortningar.
• Ta bort gammal utkommenterad kod; Git sparar historiken.
• Lägg aldrig lösenord, tokens, privata adresser eller personuppgifter i kommentarer.
• Undvik TODO utan ansvarig eller konkret nästa steg. Använd ärenden för teamets arbete.
• Uppdatera eller ta bort kommentarer när beteende eller antaganden ändras.

Exempel: komplexitet

// Förväntad O(1)-uppslagning med välfördelad hash; värsta fall kan skilja sig.
return inventoryById.TryGetValue(id, out item);

Att skriva // alltid O(1) vore ett för starkt påstående. En bra kommentar anger antagandet, men bör också fylla en verklig funktion för läsaren.

Kontrollista

Fråga om läsaren förstår varför regeln finns, om kommentaren fortfarande är sann och om ett test kan kontrollera den. Kommentarer hjälper människor; C# XML-dokumentation är särskilt användbar för publika API-kontrakt.