Strategier til at kommentere kode

/*
Tjah, det er jo smart.
*/

Ja det er ofte man synes at kommentare er unødvendige, men når man så kigger på koden 1 uge efter kan det hurtigt virke uoverskueligt. selvom man bruger logiske navnet til variabler.

Desuden er der jo nogle gange hvor man laver et eller andet helt tåbeligt bare for at rette en bug, så er det meget godt at have en kommentar der siger man ikke skal ændre noget i koden der...

Tror flere og flere begynder at kommentere sin kode "rigtigt". Måske især "nye" programmører.
Det er lækkert der kommer mere fokus på det, selvom det vist er almindelig kendt at man bør smide et par ord ind hist og her.
Det er virkelig bittert at sidde med et eller andet stort projekt man har overtaget, og der så ikke er en eneste kommentar. Det tager sgu lang tid at gennemskue tingene, hvis overhovedet muligt.
Godt flere og flere værktøjer kan hjælpe med at kommentere.

#3 nye programmører? det er da de værste til det, da de jo ofte sidder så længe med samme kode, at når det virker, er de overbeviste om de aldrig glemmer hvad det handler om.

Mens erfarne programmører har lært af deres fejl... Man skal dog også passe på ikke at kommentere så meget at det bliver svært at skelne mellem relevante og irrelevante kommentarer.

Personligt er jeg vild med den måde kommenteringen foregår i javadoc og netbeans, hvor man angiver en beskrivelse af hver metode, og evt. parametre og returværdier

så er det bare et spørgsmål om at have så lidt kode i hver metode, at det er indlysende hvad der sker, og ellers lave nye metoder som klarer tingene

kender godt det med at vågne op efter en ordenlig brandert og finde ud af at man har skrevet en 20 filers kode som man ikke aner hvordan hænger sammen.

God artikel, minder dog utrolig meget om afsnittet "Keys to effective comments" i Code Complete, af Steve McConnell.

#3 Jeg synes faktisk nye programmører er de værste, de skriver ofte irrelevante kommentarer, f.eks. "Increase variable with one" istedet for "Address next queue item". At skrive effektive kommentarer er ikke noget man bare gør fra dag 1.

#4 Desværre bruger javadoc en besynderlig @-syntaks istedet for XML og understøtter ej heller comment overloading (har du flere metoder med forskellig parametre, skal kommentarne duplikeres manuelt).

Nu han er igang, kan han så ikke også lige skrive en guide til hvordan jeg vælger variabelnavne, der rent faktisk giver mening?

Gid manden dog så kunne sætte {}'erne ordentligt, med de opløsninger man har i dag giver det ingen mening at smide dem for enden af linierne og derved ødelægge overskuelligheden.

Jeg ved godt det er en smagssag, men heldigvis følger værktøjer som Visual Studio C# det som standard og automatisk.

Folk har også en irriterende tendens til ikke at bruge {}'ere hvis der kun skal udføres en ting, ja man skal ikke men det gavner overskueligheden, specielt hvis mange ting er nested ind i hinanden. Eller at klumpe tingene sammen i en linie.

mrmoris:
XML syntax til kommentarer, tror du det er en god ide ?
Personligt har jeg altid været glad for Javadoc, ikke mindst nær man trækker dokumentationen ud af programmerne.

Javadoc er helt klart den bedste måde til kommentering og automatisk udtræk jeg har set endnu i de sprog jeg har arbejdet med.

Det med {} er altid en stor diskussion... jeg har det bedst med hvor de starter for enden af den funktion,if,switch etc. som de representere... jeg tror det er tilvænning.

kommentarer i kode skal der helst ikke være nogle af overhovedet, når man først har lavet en release udgave. Mens man udvikler kan man snildt lave lidt "//function for doing some stuff, dont forget the whatever", men i den endelige udgave skal der helst ikke være kommentarer. Folk burde hellere lave dokumentation med f.eks. javadoc eller doxygen, og så blot have en dok/comment udgave og en clean (release) udgave af koden.

min holdning anyway

(offtopic)
Der er virkelig ikke noget mere uoverskueligt end:
void some_function() {
blah blah;
blah balh;
}

Det virker ikke som noget uoverskueligt, men når du har en funktion på en 4 skærme (hvilket ikke er unormalt) er det ufattelig svært at holde styr på niveauerne, når folk ikke sætter {} par med samme indrykning.
Sun burde dø, det plejer at være Java kodestandard..

[edit]
hvordan laver man indrykning i sine posts?

#10 hvorfor ingen kommentarer i en release? jeg går ud fra du arbejder med open source (for ellers er det jo pænt ligegyldigt)
En god kommentering er imo nødvendigt for at man kan arbejde ordentligt med kode man ikke selv har skrevet.

#10:
Quote-tagget kan vist nok gøre det:

void some_function() {
blah blah;
blah balh;
}

... næ, det kunne det så ikke :(

men med indrykning er det meget overskueligt.. :)

selv sværger jeg til denne her:

void some_function()
....{
....blah blah;
....blah balh;
....if dittendatten
........{
........blah blah;
........blah balh;
........}
....blah blah;
....}

#8 Visual Studio bruger XML, fordelen er indlysende: En standard syntaks som er nem at skrive preprocessors til og så kan semantikken udvides såfremt man måtte have specifikke krav til kommenteringen.

#7 Tja, her er da et par af de regler jeg har samlet op i løbet af de sidste 10 års tid.

- Brug aldrig "temp", "tmpvalue", "x1" osv.

- Brug kun simple navne i meget overskuelige tilfælde, f.eks. indeksering i et simpelt loop med "n", "i", "j" etc. hvor der er tale om en midlertidig var som aldrig skal bruges til andet end indeksering.

- Længere sigende navne fungerer som kommentarer i sig selv, f.eks. "filesInWorkingDir", "linesPerPage" osv. Op til 4 ord sat sammen er forholdvis kort og nemt at læse.

- Fokuser på problemet, ikke hvordan løsningen er implementeret. F.eks. siger "recordArray" intet om problemet (kun at der er tale om et array af records) mens "employeeData" straks beretter om hvad der arbejdes med.

- Benyt altid komplementære navne når muligt. Dvs. har du en
"begin" har du også often en "end", "old" har du en "new", "open" har du en "close" osv.

- Lav konstanter eksklusivt i uppercase, som f.eks. "DOC_TYPE_XML".

- Udnyt at boolske variabler udtrykker primitive ting, dvs. brug "is..." eller "has..." efterfulgt af et udtryk der giver mening for problemet. F.eks. "isDone" eller "hasNext". Det sætter større krav til hvad du vælger af navn, f.eks. giver der pludselig ikke mening at have "isStatus" og du tvinges til at tænke over et fyldestgørende navn som f.eks. "isStatusOk".

- Forsøg altid at se boolske variabler konsekvent fra den positive side, altså "isSuccess" er bedre end "hasError". Hvis ikke, så vær i det mindste konsistent mht. dette valg.

- Benyt ikke globale variabler, men hvis sproget og problemet kræver det, sæt i det mindste "g_" foran for at signalere, at det ikke er en lokal eller medlemsvariabel.

- Er der tale om variabler som tilhører en klasse, sæt m_ foran disse. Det signalerer at der er tale om et medlem af klassen og ikke en lokal eller global var.

- I sprog med svag typekontrol (C, PHP, JavaScript) brug hungarian notation til variabler for at benævne disses typer. "ch" for Character, "sz" for string zero-termintated, "h" for handles osv.

- Bland ikke sprog (naturlige) sammen men vær konsekvent, i DK betyder dette som regel enten dansk men dog helst engelsk. Det bliver så nemmere for andre at læse, f.eks. hvis dele bliver postet i et spørgsmål på en nyhedsgruppe.

#14:

hellere:
void some_function()
{
....blah blah;
....blah balh;
....if dittendatten
....{
........blah blah;
........blah balh;
....}
....blah blah;
}

{}'erne stående under det der starter dem, og det skal stå parvis under hinanden

Personligt har jeg tit oplevet at have fundet en kodestump eller lign på nettet og det første jeg gør er at strippe alle kommentarene så jeg kan læse koden (det er ikke sjældent at der er dobbelt så mange linier kommentarer som der er kode).

Hvis tingene er navngivet ordentligt og struktureret ordentligt er det sjældent at det kan lade sig gøre at skrive kommentarer der ikke er selvindlysende.

Det giver god mening at skrive en projektdokumentation der forklarer hvordan systemet er tænkt og den logik der ligger bag måden at skrive koden på og hvilken kode der ligger hvor, men ud over det synes jeg som ofte at kommentarene ender med at blive sammenlignlige med:

public int GetHeight() {return FHeight;} //Gets the Height

Jeg mener heller ikke det er rimeligt at kommentere den fysik eller de spilregler der ligger bag, med mindre det er for at fortælle _hvilken_ fysisk ligning man har valgt til at regne det ud f.eks.

CalcCircleArea(double ARadius)
bør ikke følges af kommentaren A = pi r^2

Og det samme gælder for funktionen
CalcHitPointModifier(int AConstitution)
Der må man slå op i sine D&D regler hvor bergeningen er dokumenteret

Ligeledes bør men heller ikke duplikere API dokumentationen ind f.eks. bør man ikke forklare hvad windows API funktionen CreateWindowEx gør - det kan man slå op i sin API doc hvis man har brug for at vide det.

Det der er relevant at dokumentere på den ene eller den anden måde er de koncepter der ligger bag hvis de ikke er selvforklarende - typisk et resultat af performance over læselighed valg.

Hvis jeg kigger i kode jeg skrev for et par år siden kan jeg have problemer med at finde ud af hvor hvad sker, hvis jeg da ikke har skrevet det ned, men det er aldrig et problem at forstå den enkelte funktion eller klasse når først jeg har fundet den.

Det meste kode er ganske let at læse, hvis det ellers er sat pænt op og navngivet nogenlunde hensigtsmæssigt.

Kode der er svær at læse er mere hyppigt et resultat af en dårlig programør end en dårlig kommentator...

Og inline kommentarer kan ofte ødelægge læseflowet så det bliver meget svært at se hvad der sker. Ligeledes kan kommentarer ved hver enkelt metode medfører at filen bliver så lang at det bliver svært at finde rundt i den.

Så i min ydmyge mening bør man starte med at skrive sin kode så den er let læselig og så kan man tilføje kommentarer, hvor man tager handling der forekommer ulogisk eller forkert, samt skrive en overordnet dokumentation der gør at en anden person kan sætte sig ind i den tankegang der ligger bag strukturen af hele projektet.

#16
om end jeg er 100 gange mere enig med dig end jeg er med #14, så er jeg stadig uenig jeg mener at start tuborgen skal stå på samme linie som statementet som i

void some_function() {
....blah blah;
....blah balh;
....if dittendatten {
........blah blah;
........blah balh;
....}
....blah blah;
}

Men det hører vist ind under religiøse diskutioner som vi kan føre til dommedag uden nogensinde at blive enige :-)

Hmm lad os lige for sjov kigge på hans "See for Yourself" eksempel.

Kommentarene til isAllive er 100% overflødige det kan man jo allerede se i navnet.

og havde han kaldt teamCount for "i" havde den ikke behøvet kommentar.

"if(defender.agility > attacker.agility)"

Behøver ingen kommentar, hvis vi kender reglerne for spillet - og det ville i sagens natur være absurd at forsøge at kode til spillet uden at kende reglerne.

Og for-løkken er også selvforklarende vi gennemløber defender.team og tjekker om nogen af dem har counterAttack == 1 (burde nok have være boolean men hva' pokker vi forstår det jo nok alligevel) og hvis de har det så gennemføres attack(attacker).

Jeg synes den funktion havde været lettere at læse uden kommentarene forudsat man forstår spillets regler, og jeg mener at det er nødvendigt at forstå spillets regler for at kunne gøre noget meningsgivende ved koden under alle omstændigheder.

Der var en der postede følgende link på slashdot i forbindelse med denne "nyhed": http://www.cenqua.com/commentator/ - jeg synes den var ret underholdende :)

#11, det varierer, men jeg skriver kode i en stor virksomhed, og de fleste der vil ikke have kommentarer til at forurene koden. Dokumentation har de fleste ikke noget imod.

#16 er den stil jeg foretrækker.

Synes det er fedt at
"
blah blah
blah balh<--typo
"
har overlevet i alle eksemplerne :D

#19

Det er jo som man ser det. Lad os sige dit spil var lidt mere avancerede og dine enheder efter en kamp kunne få sine stats ændrede som følge af f.eks. xp osv., og hvis enhederne efter at have fået lavet et xp tjek, som udføres efter modstanderens counter attack, og som derefter kunne føre til at enheden får lov til at angribe igen alligevel.

Min pointe er at når tingene bliver mere kompliceret, så er der grund til at kommentere, og man kan ligesågodt starte med det samme, fordi ellers ender man med lige pludselig at skulle kommentere alt koden, hvilket er helvedes kedeligt.

Og hvis man som #21 helst ikke må aflevere med comments, jamen så laver man da bare et lille clean comment script, selvom jeg nu er af den holdning at kode uden kommentarer er langt mindre værd.


Btw. Foretrækker også #16 stil, har dog en tendens til at slutte og starte visse specifikke stykker kode på samme linje. F.eks.

try {
....X
....} catch {
....Y
....}

Hmmm...Ser lidt skidt ud her, men synes nu det virker meget overskueligt i koden.

#22
Hvis tingene bliver komplicerede så er det på tide du får det delt op i flere metoder med sigende navne - den i eksemplet givne metode er allerede smålang i min opfattelse.

Og alle de kommentarer der er i den er enten selvindlysende eller bare unødvendige når man kender spillets regler - og jeg mener de skal være mere end almindeligt komplicerede for at man ikke skal kunne lære dem og huske dem uden behov for comments - jeg kan huske reglerne til de første 15 spil med et komplikationsniveau omkring D20 D&D.

Og kommentarer har en klart negativ inflydelse på læsningen af koden som kode og jeg mener derfor kun de bør være der i tilfælde, hvor der ikke er anden god måde at skabe forståelse på, og deler man sin kode ordentligt op er det uhyrre sjældent et problem at skrive let læselig og forståelig kode.

#18 og andre
Det er faktisk bevist, at det giver flere fejl at placere start tuborgen på samme linje som dit statement. Det giver mere overskuelig kode hvis den kommer ned på samme linje, hvor den har en linje ned til slut-tuborgen.

Der hvor jeg arbejder skal vi faktisk holde start-tuborgen på en linje for sig af den grund.