Kommentarer som inte är API (typ Javadoc) och därmed menade att ingå i dokumentation är endast i undantagsfall inte ett misslyckande, det ska vara nåt jävligt märkligt fall där inte metodnamn med parameternamn kan förklara exakt vad som sker/ska ske. I alla fall i ett högnivåspråk (vilket är typ assembler med labels och uppåt, i det här fallet). Och finns det inget bra namn som passar, ja då är det dags att bryta isär och refactorera.
Citat:
Ursprungligen postat av
Proton
Ja det är väl en bra sammanfattning.
Man behöver inte kommentera varenda if som finns, men däremot kan det ju vara värt att i if-blocket skriva en rad om vad som ska hända om villkoret uppfylls, typ såhär:
Kod:
if(payment.getState() == PaymentState.UNPAID){
//send notification of unpaid payment.
sendUnpaidMail();
}
Ren improviserad kod, men du förstår prncipen iaf. iffen kan jag läsa själv vad den jämför, men däremot är det alltså vettigt att skriva en rad om vad koden gör om villkoret uppfylls.
Om inte sendUnpaidMail() förklarar bra nog vad som händer i sig självt så kanske metoden ska heta sendNotificationOfUnpaidPayment() och vips är kommentaren 100% redundant. Är det av ngn anledning viktigt att veta att det är mail också kan man alltid slänga in det någonstans: sendNotificationEmailOfUnpaidPayment()
Än värre är att kommentarer så ofta ljuger. Metoden kanske gjorde vad kommentaren säger för tre år sen, men nånstans ändrades logiken men inte kommentaren, det råkar man på precis hela tiden. Som yrkesprogrammerare tillbringar man ofta 95% av tiden med att läsa kod, inte skriva, och den bästa koden är den som är så lättläst att den är självdokumenterande. Kommentarer är i bästa fall i vägen, i sämsta fall villospår.
När man börjar koda så strör man ofta kommentarer i koden för
sin egen skull, för att hjälpa tankeverksamheten och hålla reda på vad man håller på med - det är helt fine! Men så fort man börjar få lite koll är det dags att vänja sig av med det och istället skärpa till koden.
Samtidigt, bra namn
och ändå kommenterat är tusen ggr bättre än dåliga namn och inga kommentarer. Så det är inte längst ner på stegen