Kodkommentarer

Kodkommentarer är text som finns i programkällkod men inte körs av programmet. Deras syfte är att förklara vad koden gör, varför vissa val har gjorts och hur komponenter ska användas. Bra kommentarer underlättar underhåll, vidareutveckling och överlämning till nya teammedlemmar.

Vanliga typer är inline-kommentarer som placeras bredvid en rad kod, blockkommentarer som avgränsas av särskilda start- och slutmarkörer, samt dokumentationskommentarer som används för att skapa API-dokumentation. Olika språk har olika syntax för kommentarer, till exempel // och / / i många C-baserade språk, # i Python, samt specialiserade doc-kommentarer.

Kommentarernas placering bör spegla innehållet: de ska förklara komplex logik, antaganden eller användning av gränssnitt, inte vad som är uppenbart. Ta även upp beslut, namnval, sidkontext och eventuella begränsningar. Användbara hissar är att märka uppgifter som TODO eller FIXME.

Dokumentationskommentarer används av verktyg för automatiserad dokumentation, som Javadoc, Doxygen eller Sphinx. De följer ofta särskilda konventioner och innehåller taggar för parametrar, returvärden och felhantering. Dessa kommentarer bidrar till att generera läsbar dokumentation utan att duplicera information i koden.

Bästa praxis inkluderar att skriva tydliga, koncisa och uppdaterade kommentarer. Undvik att kommentera det som redan går fram av koden; skriv i varför-frågan, inte bara vad. Håll stil och formatering konsekvent, uppdatera kommentarer vid kodändringar och använd tydliga märkningar som TODO eller FIXME. Avlägsna gamla kommentarer när de inte längre stämmer.