Min kode er selvforklarende!

Jeg ved ikke om det er sandt at der er forskel på den måde mænd og kvinder koder, men jeg krummer i hvert fald næsten altid tæer, når et teammedlem ytrer - "nej, selvfølgelig er der ikke nogen kommentarer - min kode er selvforklarende". Især fordi jeg oftest har hørt det fra folk der efter min mening skriver alt andet end selvforklarende kode.

For et par måneder siden faldt jeg så over en forklaring på denne forskel - det er bare fordi jeg er en pige, at jeg har den slags tendenser. Artiklen, der forklarer den lille forskel kan findes på "the Inquirer", og beskriver kvinder som hensynsfulde kodere, der bruger tid på at gøre deres kode gennemskuelig for andre, hvorimod mænd er stolte af deres komplicerede kode, som de mener alle burde kunne gennemskue.

Til tider tror jeg at visse menneskers aversioner overfor kommentarer kommer af hvordan kommentarer også kan misbruges; til at forklare linje for linje hvad programmeringssprogets konstruktioner gør - her er koden langt mere forklarende end kommentaren, men hvad med de overordnede kommentarer som fortæller lidt om begrundelsen for at koden ser ud som den gør? ("Her bruger vi Visitorpattern og denne klasses rolle er...". "På grund af krav x har vi valgt at ...").

Selv vil jeg nok putte mig i kassen med folk som forsøger at skrive så simpel kode som muligt og som kommenterer de komplicerede ting og strukturen af koden.

Tror du det virkelig er en forskel på kønnene eller er det en journalistisk forenkling' Er din kode selvforklarende' Hvilket kommentarniveau foretrækker du' Er kommentarer i andre folks kode bare forstyrrende for forståelsen og læseflowet'

Kommentarer (48)
sortSortér kommentarer
  • Ældste først
  • Nyeste først
  • Bedste først
Michael Kastoft Nielsen

Hejsa,

jeg vil sige at jeg har det lidt ambivalent mht selvforklarende kode.
Når jeg har lavet et program/klasse så er man helt inde i alle problemerne, så der vil jeg mene at det er selvforklarende.
Men så et halvt år efter så kan jeg så ikke huske hvad var logisk :)
Jeg tror at en løsningsmodel er at man får en anden til at reviwe koden og de ting den anden ikke forstår kommenterer man så.

mvh Michael Nielsen

  • 0
  • 0
Morten Krogh Andersen

Så er jeg nok en tøsedreng (også) på det område.. Jeg forsøge generelt at lave min kode så læsbar som muligt; f.eks. insisterer jeg på at metodenavne/funktionsnavne skal afspejle deres formål, og ikke have navne som jeg iøvrigt selv kun kan gætte betydningen af et par dage efter..
Begrundende dokumentation er det vigtigste, da det eliminerer megen spildtid ("gæt baggrunden") i forbindelse med videreudvikling/vedligeholdelse.

  • 0
  • 0
Per Andersen

Som gammel projektleder må jeg give dig ret i at mænd generelt er dårligere til at kommentere deres kode end kvinder - desuden er mænd generelt ikke så tilbøjelige til at følge kodestandarder som kvinder er.

Kommentarer i kode er dog ikke uproblematisk, jeg er enigt med dig i at det er godt på et overordnet niveau, men nogle er tibøjelig til at dokumentere selvfølgeligheder.

Der hvor kæden oftest hopper af, er under vedligeholdelsen af et system, det kan være svært at få opdateret kommentarer og anden dokumentation, når der laves fejlrettelser og systemændringer.

Det er ingen spøg at overtage et 20 år gammelt system skrevet i COBOL, med kommentarer der ikke længere stemmer overens med det programmet faktisk udfører, så kan kommentarerne faktisk gøre ondt værre.

mvh Per Andersen

PS. Det er dejligt at høre at der stadig er liv i datalogi i Århus - kommer du i Tågekammeret?

  • 0
  • 0
Ib Højme

It was hard to code, it should be hard to understand ;-)

Men ellers holder jeg mig til beskrivende klasse/metode/variable navne, kommenter det væsentlige, kommenter hvis ændringer bryder med den oprindelige logik.

  • 0
  • 0
Nicolai Buch-Andersen

Jeg plejer gerne at bryde mine metoder ned i to-tre paragraffer. Hver paragraf får så gerne en "overskrift" i form af en kort kommentar. Lidt ligesom en artikkel brydes ned i flere sektioner med hver deres header. Det gør det lettere at skimme koden uden at behøve at nærlæse logikken.

Hvis der er flere en to-tre paragraffer i en metode, så er det gerne tid til at begynde at anvende "compose method" til at bryde den ned i mindre bider.

  • 0
  • 0
Per Andersen

I øvrigt mener jeg at det er meget vigtigt med kommentarer i koden, når man er blevet kaldt på arbejde påskemorgen p.g.a. et kritisk problem, har man som regel ikke meget tid til at gennemlæse systemdokumentation.

mvh
Per Andersen

  • 0
  • 0
Poul-Henning Kamp Blogger

Det var sådan set noget af det samme jeg holdt foredrag om til Open Source Days, men en bid mere generaliseret.

Rent ideologisk er kommentarer noget skrammel fordi de er udenfor compilerens rækkevidde.

Den information der indeholdes i kommentaren gavner dermed ikke programmets faktiske kvalitet, men tjener udelukkende som en, ofte historisk, fodnote til kildeteksten.

Jeg prøver derfor meget at finde metoder hvor denne information faktisk bliver en del af programmet.

De kommentarer der herefter er uundgåelige, giver den kontext der ikke er at finde andre steder, eller referencer
til information udenfor kildeteksten, så som "Timer3 virker ikke i count-down mode, se errata xyz034, derfor tæller vi opad selv om det er mere besværligt."

Personligt får jeg flip af kildetekster med indbyggede novellesamlinger, men lige så meget pisser kildetekster uden de nødvendige kommentarer mig af.

Poul-Henning

  • 0
  • 0
Per Andersen

Jeg vil give PH helt ret.
Principielt kan man betragte koden som en måde at nedbryde en overordnet (kompleks eller måske snarere komprimeret) problemstilling til noget meget simpelt (maskinkode), hvor maskinkoden så til gengæld er meget voluminiøs.

Hele systemudviklingsprocessen går så ud på at nedbryde den oprindelige problemstilling til nogle mindre komplekse dele. Dette er der så mange forskellige udviklingsmetoder til, afhængig af problemstillingen (f.eks. den objektorienterede).

Under alle omstændigheder har man som menneske brug for at vide, hvordan de forskellige dele hænger sammen, og hvad den enkelte del laver, dette gælder specielt i pressede situationer.

Principielt set står det i koden, men enkelte af os læser klar tekst hurtigere end kode, og specielt som PH nævner, hvis det drejer sig om referencer udenfor koden kan det være nødvendigt med kommentarer (selv om sådanne ting selvfølgelig også er dokumenteret andre steder?)

Mht. at nedbryde til mindre moduler, skal man også passe på - noget af det værste spaghettikode, jeg har set var skrevet i C++

mvh
Per

  • 0
  • 0
Hans-Kristian Bjerregaard

Din kode skal være selvforklarende med hensyn til HVORDAN du gør. Dvs at det skal ikke være svært at se hvad koden laver med de forskellige variabler. Dette kan klares ved god og forklarende navngivning af klasser, variabler, funktioner osv.

Hvis man dog gør noget helt kryptisk, der mere nærmer sig sort magi, kan det være nødvendigt at give en kort kommentar til hvorfor man lige præcis gør dette på den pågældende måde.

Til gengæld bruger jeg en del kommentarer til indledende at forklare HVAD koden gør. Altså hvad bidrager denne del kode med til resten af systemet.

Når man hved hvad noget kode gør er det også meget nemmere at se hvordan den gør det.

  • 0
  • 0
Per Andersen

Jeg synes, det er bemærkelsesværdigt, at det kun er mænd, der kommer med indlæg, at de alle mener, at de skriver gode kommentarer, og at jeg er den eneste, der forholder sig til kønsforskellene.

  • 0
  • 0
Therese Hansen

Jeg kan godt li' tanken om et review, og reviews er jo noget man gør med meget komplicerede dele af koden, som sikkert også er de dele, der mest behøver kommentarerne. Der er typisk bare ikke tid til at reviewe ret store dele af koden i min verden, så der skal også være en strategi til resten.

  • 0
  • 0
Brian Rasmussen

Uden at have faktiske tal at trække på vil jeg tro, at jeg nok har set flere dårlige end gode kommentarer i min tid som udvikler, så hvis jeg skal bruge det som målestok for noget i denne sammenhæng, bør der nok skrives færre kommentarer.

Jeg er desuden helt enig med PHK om at forklaringerne så langt hen ad vejen som mulig bør forklares i kode og ikke i kommentarer. Fornuftig navngivning og opdeling af koden kan gøre meget for dette.

Jeg er også meget enig i, at man bør tænke på dem, der skal læse koden fremover, og her skal man huske, at de ikke eller i hvert fald kun ganske sjældent er tankelæsere.

  • 0
  • 0
Therese Hansen

Jeg har arbejdet sammen med en fyr, der kun ville have variablenavne og metodenavne som 3 bogstavsforkortelser - og tit var det ikke længere forkortelser, men bare bogstavskombinationer, fordi der så ellers ville være sammenfald. Projektet var småt, men jeg må indrømme at det nok er det projekt jeg mindst har lyst til at kigge på igen. Sigende navne er utroligt vigtigt.

  • 0
  • 0
Therese Hansen

<off topic>
Hej Per. Der er masser af liv på datalogi i Århus og ja, jeg kommer en del på Kammeret - eller rettere det gjorde jeg, da jeg ikke skrev speciale. Er du tidligere kammergænger?
</off topic>

Vedligeholdelse af kommentarer ser jeg også som et stort problem. Jeg ved ikke helt hvad man kan gøre ved den slags ud over at have disciplin til at huske at rette kommentarerne til.

Det er sjovt at artiklen om kønsforskellene rent faktisk passer med din erfaring - jeg må indrømme at jeg så det som lidt af en journalistisk tilsnigelse, men det kan da være der er noget om snakken. Kvinder er generelt set nok også lidt mere vant til at rydde op og mere pernitne, når det gælder om at holde orden - i hvert fald hvis man skal drage paralleller til hjemmet (og absolut se bort fra mig som repræsentant for mit køn - jeg er mere til virtuel orden end orden i hjemmet).

  • 0
  • 0
Per Andersen

Jeg var medlem af tågekammeret fra 1970-1978. Nåede en overgang at være suppleant til bestyrelse. Dengang holdt vi fester sammen med de franskstuderende - det kom der meget interessant tværfakultetssamarbejde ud af.

En overgang var jeg udvikler-projektleder-vedligeholder på diverse systemer skrevet i COBOL. Der var ude for en gut, der skrev noget, jeg bedst kan beskrive som destruktiv kode:

PERFORM SOMETHING
GOTO SOMEWHERE
GOTO HELTFAERDIG
etc.

Det var en god reminder i nødvendigheden af at være omhyggelig med sin navngivning.

I samme firma havde man fundet ud af det altid var når man skulle læse filer at fejlene viste sig (det var batch-programmel) så de havde i deres visdom fundet ud af at der kun måtte være et read-staement pr fil - det gjorde så at programlogikken blev helt kryptisk.

  • 0
  • 0
Thomas Ammitzbøll-Bach

Dårlige kommentarer
[code="java"]
void bubbleSort(int numbers[], int array_size)
{
int i, j, temp; // Her erklæres variablene

for (i = (array_size - 1); i >= 0; i--) { // tælleløkke 1
for (j = 1; j <= i; j++) { // tælleløkke 2
if (numbers[j-1] > numbers[j]) { // betingelse
temp = numbers[j-1]; // tildeling af temp
numbers[j-1] = numbers[j]; // tildeling af numbers-element
numbers[j] = temp; //tildeling af andet element
}
}
}
}
[/code]

Bedre kommentarer
[code="java"]
void bubbleSort(int numbers[], int array_size)
{
int i, j, temp;

for (i = (array_size - 1); i >= 0; i--) {
for (j = 1; j <= i; j++) { // Det i'te element vil altid finde sin plads
if (numbers[j-1] > numbers[j]) { // hvis den største står forrest
temp = numbers[j-1]; // ombyt de to værdier
numbers[j-1] = numbers[j];
numbers[j] = temp;
}
}
}
}
[/code]

  • 0
  • 0
Henrik Jensen

Jeg er helt enig i at koden generelt skal være så selvforklarende som muligt og der er jo et hav af forskellige måder at forbedre læsbarheden på (navngivning, korte metoder, lav kompleksitet m.v.)

Så når man via en god kodekvalitet kan læse 'hvad' ud af koden så er det langt at foretrække, men min erfaring er dog at nogle gange når man er ude i at udvikle generiske frameworks m.v. så kan koden være så abstrakt at det på udvalgte steder alligevel er meget rart at få forklaret 'hvad' man ser. Men kommenteringen skal ikke være til afhjælpning af dårligt designet kode.

Men så er der jo også 'hvorfor' som til gengæld ofte er langt mere interessant at kommentere i koden fordi at det jo ofte også forklarer ting du ikke kan læse ud fra koden, 'hvorfor' handler jo lige så meget om hvad koden ikke gør som hvad den gør.

  • 0
  • 0
jan nielsen

Jeg mener faktisk at linjekommentarer i videst muligt omfang bør undgås. Problemet med linjekommentarer er at de oftest er en indikation på at de liner af kode som linjekommentaren kommenterer repræsenterer et en separat opgave eller et andet abstraktionsniveau end de linier af kode som de er indlejret i:

public void populate() throws Exception{
Connection = null;
try{
// getDatabase connection
Class.forname(DRIVER_CLASS);
c = DriverManager.getConnection(DB_URL, USER, PW);
// create result set
Statement stmt = c.createStatement();
ResultSet rs = stmt.executeQuery(SQL);
// add parts to list from result set
while(rs.next()){
Part p = new Part();
p.setName(rs.getString("name"));
partList.add(p);
}finally {
c.close();
}
}

I ovenstående stump kode er et eksempel på 'too much information'. Der beskrives en masse detaljer om hvordan man skaber en forbindelse til en database og hvordan man hiver rækker ud af et resultat set. Men på dette her niveau ville jeg egentligt være tilfreds med en overordnet beskrivelse af hvad metoden 'populate' gør og i hvilken rækkefølge den gør det. Hvorfor skal jeg partout belemres med alle de grimme detaljer om hvordan forbindelsen til databasen bliver skabt - er det ikke
nok for mig at vide at der bliver skabt en forbindelse og ikke hvordan. Hvis jeg vil vide præcis hvordan forbindelsen skabes så kan jeg opsøge den information når jeg vil.
Den megen information forvirrer læseren, det bliver uklart hvad det overordnede formål med metoden 'populate' egentligt er. Derudover nedsættes testbarheden og genbrugsmulighederne. Det hjælper selvfølgeligt en lille smule at programmøren har indsat linjekommentarer. Men egentligt virker disse kommentarer mere som et plaster på et åbent benbrud. Programmøren kan godt fornemme at der er et eller andet galt og har derfor forsøgt at lappe koden med et par kommentarer. Men der skal mere end hæfteplaster til at behandle et åbent benbrud.

En mulig behandling kunne være Single Layer of Abstraction Principle (SLAP - og sikker andre navne)

-opdel dit program/metode i metoder som udfører en og kun en opgave
-hold alle operationer i en metode på samme abstraktionsniveau

Benytter man disse principper på ovenstående kode får man:

public void populate() throws Exception{
Connection c = null;
try{
c = getDatabaseConnection();
ResultSet rs = createResultSet(c);
while(rs.next())
addPartToListFromResultSet(rs)
} finally {
c.close();
}
}

  • 0
  • 0
Henrik Jensen

Bør man kommentere på dansk eller engelsk? Bør man lave danske eller engelske variabelnavne? Hvem er den næste programmør?

Det er et rigtigt godt spørgsmål. For det første når vi nu snakker om at kildekoden skal være selvforklarende så snakker vi jo faktisk ikke kun om hvorvidt at kommentarer skal være på dansk eller engelsk men faktisk også om man benytter dansk eller engelsk navngivning af klasser, metoder m.v.

Jeg vil som udgangspunkt foretrække engelsk af netop den årsag at så er det altså lettere når du pludselig finder ud af at en del af det fremtidige vedligeholdelsesarbejde outsources til udlandet.

Men, for der er et stort men. Jeg har også siddet på projekter som indeholdte rigtig meget forretningslogik og med brug af mange faglige termer fra den danske lovgivining m.v. Nu valgte vi faktisk at benytte dansk i domænemodellen, men vi overvejede engelsk kraftigt, men fandt at for det første var det faktisk svært altid at finde nogle passende termer og samtidigt ville det blot øge sprogbarriererne mellem fagfolkene og udviklerne yderligere.

Det man jo så i sagens natur endte op med var jo sådan lidt et dansk-engelsk mix, fordi at man jo så modsat selvfølgelig ikke sad og oversatte mange engelske IT-fagudtryk til dansk. Lidt ligesom når Therese har benyttet Visitorpattern og ikke "Besøgende mønster" i hendes kommentarer.

Hmm Jeg kan faktisk se at nogle benytter f.eks. oversatte navn på sådan noget som f.eks. designmønstre. el patrón visitor, visiteur, Besucher Entwurfsmuster etc. Det bliver jeg nok aldrig sådan en vild fan af.

  • 0
  • 0
Klavs Klavsen

Jeg skriver normalt en "opskrift" i punktform på hvad den pågælden funktion/kodestump skal gøre - og så skriver jeg koden omkring den "opskrift" så den bliver til kommentarerne, så man således direkte kan aflæse hvad der sker.

Tror bare nogle kodere (mænd måske i højere grad?) er rodehoveder af natur og det afspejler sig dermed i deres kode.

  • 0
  • 0
Jens Madsen

Dengang jeg lærte datalogi, var der stor uenighed i om variabelnavne skulle være lange og selvforklarende, eller korte, og overskuelige. Læren mente, at variablenavne skulle være korte og overskuelige. En algorithme, kunne blive særdeles besværligt at overskue, hvis den druknede i lange variabelnavne, og simple ting måtte skrives på flere linier. Andre mente, at en lille roman, burde gemmes i hvert variabelnavn, og de bestod ofte af mellem 3 og 12 ord, med understreg imellem.

Trods alle de forskelligheder, mener jeg, at vi kom til at det bedste var at konstante, objekte, procedurer osv. helst skulle have et navn, så det var tilstrækkeligt forklarende. Derimod, måtte lokale variable, såsom x, i, osv. gerne være enkeltbogstavs eller tobogstavs. Her, var bedre, at beskrive funktionen som kommentar, sammen med erklæringen, der jo altid er tæt på anvendelsen ved lokale variable (f.eks. i et scop). Det var unødigt, at have en lille roman, for hver gang den bruges.

Genneralt, skulle forklaringen på en variabel, ikke beskrives i navnet. Navnets eneste funktion, er at kunne huske funktionen. Selve forklaringen, skal - hvis den står i koden - stå ved erklæring. Er en variabel erklæret umiddelbart før, med forklaring, f.eks. i et scop, og anvendes kun kort, betyder det ofte mere, at algorithmen er overskuelig, og ikke deles over mange linier. Her, behøves ikke, at gøres meget ud af at "huske" navnet, ved at give et langt navn, fordi at erklæringen, og dermed beskrivelsen er umiddelbart før, og naturligvis kendes og huskes. Deles koden derimod, over flere sider, så erklæringen ikke er lokal i et scop, men er længere væk, er vigtigt at den kan huskes.

Der gælder derfor næsten en regel om, at jo længere borte fra brugen at en variabel er erklæret, jo bedre skal den dokumenteres, ved velvalgt navn. Derudover, er eneste korrekte sted, at grundigt dokumentere, ved erklæringen, og det skal ikke gøres i hver enkelt brug af variabel eller funktion. Detaljeret dokumentation, er ofte bedre i en rapport, der også muliggør at kode kan opbygges i bidder, så man gradvis viser, hvordan resultatet er opnået. En algorithme, som er optimal skrevet, vil ofte kunne "vises" som programmer, der gradvis manipuleres, på samme måde, som matematiske ligninger, og dermed vises i en rapport, at algorithmen er korrekt. Mange antager, at "genierne" nemt kan overskue alle "mellemligningerne", men som i matematik, er det altså dem der tæller, og gør det læseligt og simpelt at gennemskue det beviselige. Der er ingen grund til, at programmer skal være "overskuelige", hvis de f.eks. indeholder algorithmer - deres overskuelighed, afhænger altid af rapporten, som er nødvendig. Koden, kan så henvise til rapporten, men skal helst indeholde en black-box forklaring.

  • 0
  • 0
Rasmus Kaae

Jeg synes det er ret vigtigt at skelne mellem kode-dokumentation og design-dokumentation.

Efter min mening kan kode tit godt være selvforklarende, specielt hvis man indfører visse regler som god navngivning til variable, datatyper, funktioner, osv. Jeg har tidligere været på et projekt hvor vi brugte en konvention om at hvis et område af en funktion behøvede særlig forklaring, så var det nok en idé at lave en særskilt funktion med et beskrivende navn.

Omvendt mener jeg at det er strengt nødvendigt at dokumentere design i prosa eller på diagram. Gerne i form af doxygen-kommentarer så man har mulighed for at læse design-dokumentation uden at se koden (og kan opdatere kode og design uden at skifte værktøj).

  • 0
  • 0
Carsten Sonne

Lidt off topic, men alligevel relateret. Jeg fik jeg engang denne mail fra en kollega. Den fortæller generelt om kodestil, herunder navngivning af variabler.

Jeg syntes selv den er ganske underholdende :)


  1. Use LOTS of global variables. Distribute globals evenly between session, application, cookies and usertables and use describing names like “Counter”, “Value”, “Action” or “ID”.

  2. Make sure that every part of the code and database depends heavily on as many globals as possible and make sure to modify them as many places as possible. This is called flexible design.

  3. Don’t hesitate to reuse functions or part of functions for completely different purposes. It’s better to combine several functions into one BIIIG function and pass the desired purpose as a combination of several arguments and/or globals. This is called efficient use of code.

  4. Names all your database objects throuroghly describing what they are instead of what they are used for. Save place by abbreviating the purpose of the objects instead. Good naming examples are: “spx_Get_Adminpage_Data_ usr_old3”, “spx_Get_ Adminpage Data uw_ test3_dontdelete”. This hints the reader of your code with valuable information like “I’m calling a stored procedure that returns data, to the page named “Adminpage” (Which by the way the reader is probably already located at, although [Pagename] shouldn’t restrict you to call the procedure from only that page)

  5. But most importantly make sure all procedures exists in several almost identical versions. By never deleting anything you ensure stability and backwards compatibility of your product.

  6. Take advantage of the great features of webdesign. HTML can be modified from practically everywhere. You can create it dynamically from a database, hardcode it in a webpage, generate it from ASP and even alter it on the fly using client side javascript, which can be created dynamically as well. Not a single tag should be displayed without involving all four technologies at least once.

  7. Never build your HTML from ground and up. Instead have a basic template and modify it by swapping variable references, ids, tags and injecting javascript. Functions like Replace, InStr are great for building “dynamic” webpages. Such techniques demonstrates your superior knowledge of webprogramming and it’s fun to watch the baffled expression of your colleagues as they try to figure out your brilliant code.


God dag :)

Mvh
Carsten Sonne Larsen

  • 0
  • 0
Død Profil

Taler vi om kode-dokumentation, kan jeg også tilslutte mig "Paragraf-metoden", men der udover, så ser jeg kommentarer i koden, som kommentarer til den der har lavet det, så man kan huske hvad det lige var man tænkte mens det stod på.

Andre folks kommentarer kan jeg sjældent bruge til noget, det ligemeget om de er gode eller dårlige jf. Thomas Ammitzbøll-Bach's indlæg.

Sidder jeg med et problem i noget kode andre har skrevet, så er det koden jeg bliver nødt til at analysere. Det hjælper mig ikke rigtigt hvad andre tænkte dengang de skrev koden.

Sidder jeg med et problem i noget kode jeg selv har skrevet, så kan mine egne kommentarer hjælpe med at huske hvad det var jeg tænkte dengang jeg skrev det, og (måske) hjælpe til at komme tilbage i den tankegang lidt hurtigere.

Det er sjældent jeg får bug-reports på andre folks kommentarer (selvom det er sket, suk ;-) )

Mvh,
Søren

  • 0
  • 0
Kenneth Geisshirt

Rent ideologisk er kommentarer noget skrammel fordi de er udenfor compilerens rækkevidde.

Du er inde på noget meget centralt for problemet med kommentarer er, at du ikke kan være sikker på om der er konsistens mellem kode og kommentarer. Og koden er jo det, som compileren ser, så det er den som er "sandheden".

Inkonsistens opstår typisk ved at en eller anden lige skal rette en mindre fejl mange måneder efter at koden oprindelig blev skrevet og sat i produktion.

Jeg har aldrig brugt Knuths "literate programming", men jeg gerne høre om andres erfaringer.

  • 0
  • 0
Torben Mogensen Blogger

Jeg synes, at man bør kode, så koden faktisk er selvforklarende. Eksempler:

  • Hvis du skal repræsentere et valg mellem nogle få mulige værdier, så lav en ny type, hvor disse valg er angivet, i stedet for at bruge heltal eller strings.

  • Hvis koden antager, at en bestemt betingelse er opfyldt, så lav en assertion eller test for betingelsen og rejs en undtagelse, hvis den ikke er opfyldt. En kommentar om antagelsen kan nemt overses, når man genbruger koden andetsteds eller laver om i konteksten.

Udover, at dette undgår, at kommentarerne kommer ud af trit med koden, så hjælper det også compileren til at fortælle dig, når du gør noget galt.

  • 0
  • 0
Henrik Jensen

Andre folks kommentarer kan jeg sjældent bruge til noget, det ligemeget om de er gode eller dårlige jf. Thomas Ammitzbøll-Bach's indlæg.

Sidder jeg med et problem i noget kode andre har skrevet, så er det koden jeg bliver nødt til at analysere. Det hjælper mig ikke rigtigt hvad andre tænkte dengang de skrev koden.

Der er jeg ikke helt enig, men jeg kan se at jeg har folk imod mig. Jeg fik i hvert fald mange minus da jeg tidligere skrev om forskellen på 'Hvad' og 'Hvorfor' i kommenteringen

Et par eksempler på 'Hvorfor' kommentering:

"Har benyttet metode XXX i standardkomponentet YYY
i stedet for NNN da der en fejl i komponentet der gør at....."

"Har valgt en implementering der følger XXX pattern frem for YYY pattern da jeg oplevede nogleperformanceproblemer som blev løst ved at benytte XXX pattern i stedet"

Jeg mener at sådanne kommentarer er rare fordi at det gør at jeg ikke dummer mig og måske refactor den pågældende kode til noget som andre allerede har haft dårlig erfaring med. 'Hvorfor' kommenteringen siger altså ikke kun noget om den kode man ser men også den kode man ikke ser.

Det holder jeg stadig fast i, så må jeg se om jeg får flere eller færre minus point denne gang :-)

  • 0
  • 0
Jens Madsen

Min opfattelse, at procedurer, funktioner, og objekte, er at de skal have en fornuftig grund. Man bør altså ikke lave en overflødig procedure, eller rutine, "bare" fordi, at det er selvforklarende - i stedet skal man straks tænke, om denne funktion virkelig er en fordel at have som selvstændig funktion, og om det giver mening. Formålet, skal gerne være, at vi andre steder i programmet kan anvende det pågældende objekt, metode, funktion, procedurer, osv. til det samme problem. Men ofte, hænger det sammen - for hvis vi af forklaringsårsager ønsker at indføre en procedure, er det ofte fordi, at det giver mening. Med dette mener jeg ikke, at det er "dumt" at gøre - kun at man skal tvinge hjernevindingerne til at blive brugt en ekstra gang, for at overveje muligheden for, at det man er i gang med, er af genneral karakter, og bør være en metode, der kan laves globalt, og bruges fleksibelt, til samme overalt i programmet. Liste, har man måske mange af, hvor noget skal tilføjes. De bør bruge samme kode, hvis det er samme problem.

Hvis, at proceduren/funktionen/objektet, ikke giver mening globalt, skal den deffineres så lokalt som muligt. Helst indenfor det pågældende scop, som den bruges i. Eventuelt nested procedure, i samme objekt som private osv. Den må aldrig kunne bruges ekstern, hvis den ikke er egnet for dette.

En tredie ting, er at jeg hader at anvende "new" i klasser, procedurer osv. Dette er årsag til mange memory leaks. Mange sprog, såsom C og C++, gør at det næsten er umuligt at undgå. Jeg synes, at man altid skal tænke sig om en ekstra gang, og se om man kan fjerne denne brug. Som eksempel, kan vi tage "johan bjørn"'s kode. Her er koden:

Part p = new Part();
p.setName(rs.getString("name"));
partList.add(p);

lagt ind i addPartToListFromResultSet(rs) hvilket betyder, at denne indeholder new. Jeg foretrækker, at lave et objekt, der indeholder
p.setName(rs.getString("name"));
partList.add(p);
i en konstruktør, eventuelt med rs.genstring("name") som parameter. Årsagen er, at jeg derved undgår, at have new i procedurer. Mit system er, at jeg til enhver tid, skal kunne undgå anvendelsen af new, hvis jeg ønsker at oprette det som en instans istedet - ligegyldigt, om det er en statisk instans, eller instans placeret på stak. Så kan man også vælge, at bruge new i hovedprogrammet, men er kun brug for instansen i kort tid, kunne den også være erklæret i et lokalt scop, og vil automatisk blive konstrueret, og destrueret.
I stedet for addPartToListFromResultSet(rs) kunne vi have et objekt AddPart, der arver part, og har vores konstruktør. Et nyt element tilføjes, ved at creere en instans af AddPart, og den knyttes automatisk til listen. Når en instans fjernes af AddPart, vil dens destruktør automatisk fjerne den fra listen. Vi kan selv vælge, om instansen skal være global statisk, om den skal være lokal i scop, eller om den skal oprettes med new, og kunne fjernes med delete som her. Den store fordel er, at vi får langt bedre styr på vores hukommelsesforbrug, og direkte kan bede om at få oplyst størrelsen af AddPart. Og derfor ved vi, at hver gang, vi tager en instans af AddPart, så vil den blive tilføjet til vores hukommelse.

Jeg vil nok ikke kalde den AddPart, men måske finde på et bedre navn, afhængig af hvad part egentligt indeholder af data. I princippet, kan man have objekter, såsom rød-sort træer der arves, og herefter bygge data på træet, ved at arve rød-sort træet. Og samme, med mange andre typer træer og liste.

Vi skal altså altid, kunne tilføje en instans, eller fjerne en instans, og meningen med konstruktør og destruktør, er at stå for trådning, og fjernelsen af trådningen, når instansen tilføjes og fjernes. Vi skal altid, kunne selv vælge, om en instans skal være på heap, på stak, eller i datasegmentet. I næsten alle tilfælde er det muligt, men C, og C++, synes jeg ikke lægger automatisk op til det. Typisk, vil vi have nogle grundstrukturer til lister, som vi arver, og så hæfter de data på som ønskes. Oprettes et objekt, bliver det automatisk tilføjet, og fjernes det, vil det automatisk fjernes og detrådes. Laver vi en rutine, som Add et eller andet, der tilføjer, glemmer vi måske at kunne fjerne og detråde. Det husker vi, når vil laver et objekt for formålet. Har vi en konstruktør, der tråder, skal vi også have en destruktør, der detråder. Og så opnås, at vi aldrig glemmer at detråde og fjene vores element. Og vi får ikke nemt memory leak problemer. Vi kan bruge sizeof objektet, eller instansen, og har mulighed for at se, hvor meget creering af instansen faktisk fylder, så vi har overblik over forbruget. Compileren, gør det desuden ofte mere effektiv, da vi måske undgår new, og kan oprette det på stak, eller statisk. Mange typer problemer undgås, når vi har standard rutiner, som vi arver, der står for at huske pegere for liste og træer, samt indeholder konstruktør og destruktør, som vi så arver. Og vi ved, at vi altid skal huske destruktøren, der detråder.

  • 0
  • 0
Per Andersen

Det eneste jeg kan uddrage af denne debat er at alle er enige om at de selv skriver gode kommentarer; det er lidt uklart om andres kommentarer kan bruges til noget.

Tilsyneladende er der ikke mange her, der har erfaringer med at vedligeholde andres kode - formålet med at skrive kommentarer er jo netop at andre skal kunne vedligeholde koden. Man skal altid tænke på at det f.eks. i den financielle sektor ikke er unormalt at en applikation har en levetid på 10 til 20 år.

Er der ikke nogen vedligeholdelsesfolk der kan komme på banen? - eller er debatten startet i et forkert forum?

  • 0
  • 0
Poul-Henning Kamp Blogger

Er der ikke nogen vedligeholdelsesfolk der kan komme på banen? - eller er debatten startet i et forkert forum?

Langt over 3/4 af mit FreeBSD kernearbejde har været vedligeholdelse og refactoring af gammel kode.

Det er sjældent at kommentarerne har hjulpet synderligt.

Poul-Henning

  • 0
  • 0
Michael Nielsen

Jeg arbejder som udviklingskonsulent og ser en masse kode mange forskellige steder, ens for dette er at jeg aldrig nogensinde i mine kodeår har siddet med et stykke kode hvor jeg er blevet klogere af eller hjulpet på på vej af en kodekommentar. Jeg er derimod blevet blevet direkte vildledt og forvirret utallige gange af disse kommentarer. En godt arkitekturdokumentation er brugbar, det andet er ikke.

Den her har jeg set til hudløshed:

//returns or sets the document id
int DocumentId {get;set;}

Mage til spild skal man desværre ikke lede længe efter...

  • 0
  • 0
Henrik Jensen

Formålet med at skrive kommentarer er jo netop at andre skal kunne vedligeholde koden. Man skal altid tænke på at det f.eks. i den financielle sektor ikke er unormalt at en applikation har en levetid på 10 til 20 år.

Min erfaring som primært stammer fra fagsystemer er at veldesignet/velskrevet kode + gode automatiserede tests er langt vigtigere i forhold til vedligehold end dokumentationen. Derved ikke sagt at man slet ikke skal dokumentere noget som helst, men blot at hvis kodekvaliteten er dårlig samt det er svært at overskue konskevensen af ændringer (her kommer automtiserede tests også ind i billedet udover kodekvaliteten) så er det næsten lige meget hvor god at dokumentationen er, så er systemet stadig tungt at vedligeholde.

Derfor har det også undret mig når jeg gang på gang har siddet på leverandørsiden og set kunden gå utrolig meget op i systemdokumentation, med masser af krav til indhold, udførelse af reviews m.v. netop med henblik på fremtidig vedligehold og eventuel overdragelse af koden til anden leverandør, mens at de i værste tilfælde ikke har haft så meget som et eneste krav der omhandler kodekvalitet, review af kildekoden m.v.

  • 0
  • 0
Jens Axboe

Kommentarer kan bestemt være 100% spild af tid, hvis de går helt ned på begynder niveau og kommenterer for loops med

/* loop from 0 to MAX_EVTS */
for (i = 0; i < MAX_EVTS; i++)

men ellers synes jeg bestemt det er rart med kommentarer omkring hensigten af koden, ikke hvordan den er implementeret (det kan man jo selv læse). For mig er det ikke noget problem at 'læse forbi' kommentarer hvis jeg blot vil forstå koden.

I enkelte tilfælde er det absolut et MUST med en kommentar. Feks ved brug af memory barriers i koden - er man her bange for ordering, eller er det en data dependency af en art? Det kan tage lang tid at finde ud af og kræver forståelse af hele koden, hvis der ikke er en passende kommentar tilknyttet.

Ellers er jeg også stor tilhænger af kommentering som compileren også kan se, i form af assert() eller tilsvarende varianter i det projekt man nu arbejder i.

Min personlige erfaring er at gode programmører kommenterer deres kode passende, begyndere kommenterer for meget og forkert, dårlige programmører kommenterer ikke.

  • 0
  • 0
Per Andersen

Når man skal vedligeholde eller fejlrette gammel kode, kan det være godt overordnet at få at vide hvilken sammenhæng koden indgår i og hvad den formodes at gøre.

Problemet med for detaljerede kommentarer er, at de beskriver, hvad programmøren tror koden udfører ikke hvad der rent faktisk sker, så når man skal rette fejl eller ændre koden kan kommentarerne være direkte vildledende.

  • 0
  • 0
Carsten Sonne

Meget af den dokumentation der findes på MSDN er autogereret direkte ud fra kommentar i koden. Det samme er de informationer man kan se i intellisense i VS, det være sig fra .Net frameworkes egne klasser, 3. parts komponenter og faktisk også egen kode.

Jeg syntes personligt, langt det meste af den dokumentation (og dermed kodekommentar), er værdifuld for mig. Den vil jeg nødig undværer.

Mvh
Carsten Sonne Larsen

  • 0
  • 0
Jens Madsen

At udvikle et godt program, er ikke bare at sætte sig ned og kode. Ofte, skal hjernen i gang først - der skal opdages/opfindes algorithmer, der skal tænkes grundigt over metoden osv. Ofte, får man forskellige idéer, og skal opveje disse i forhold til hinanden. Derfor, er dokumentation vigtigt, da man gerne skal komme igennem denne process, når en dokumentationen laves. Dokumentationen, er et arbejdsredskab, hvor der arbejdes med problemet, før der kodes. Opgaven analyseres, og der overvejes algorithmer, kompleksiteter, metoder og meget andet - og er forskellige former for løsninger, overvejes de i forhold til hinanden. Også processen, med at sætte sig ind i en opgave, vil ofte kræve dokumentation, da skrivningen af dokumentationen hjælper en, til at få overblik, og få dokumenteret, hvad opgaven går ud på. Måske skal kunden [eller den overordnede] bekræfte dokumentationen, og at opgaven er korrekt forstået, inden der fortsættes. Dokumentation er et arbejdsredskab - ikke noget der "klistres" på programmer. Det kan umuligt stå i et program, da det gøres før udviklingen startes, for at ikke udvikle på noget, som er urelevant. Skal det gå hurtigt, vil dokumentation ofte være dårligt skrevet og bære præg af, at være en klade, der har været et arbejdsredskab, i forbindelse med analyse, og løsning, af problemet. Men, det er alligevel nødvendigt, og kan være vigtigt, i forbindelse med intern dokumentation. Ofte, vil programmøren, specielt have gjort opmærksom på faldgrupper, hvor ting er gjort på anden måde, end man umiddelbart skulle tro, eller indeholde dokumentation om "hvorfor" det er gjort på netop den pågældende måde. Måske er sammenlignet med andre metoder, og beskrevet hvorfor at de er vraget. Dokumentation er det som viser, at der faktisk er arbejdet med et problem, før der begyndes kodning. Er der ingen dokumentation, er programmøren vist til fyring.

Min erfaring som primært stammer fra fagsystemer er at veldesignet/velskrevet kode + gode automatiserede tests er langt vigtigere i forhold til vedligehold end dokumentationen.

Men det skal jo også dokumenters, at tests faktisk er udført, og hvordan. Ved programmøren, at den er gal med koden, er det dumt at bruge den - så en programmør bør også attestere, at koden er i orden, og at den efter programmørens bedste overbevisning er uden fejl.

  • 0
  • 0
Poul-Henning Kamp Blogger

Men det skal jo også dokumenters, at tests faktisk er udført,

NB: KÆPHEST ADVARSEL!

Der findes et værktøj der er ukendt i vide kredse, således tydeligvis også her, til netop det formål.

Det hedder enten "tcov" eller "gcov" på alle civiliserede systemer og hvis dit system eller udviklingsmiljø ikke tilbyder "basic block profiling" i en eller anden form, bør du smide det ud.

Takket være mine 98 testcases og gcov, ved jeg at 82.57% af kildeteksten i Varnish er blevet udført.

Poul-Henning

  • 0
  • 0
Jens Madsen

Men er 82.57% så nok? Antages, at der er en "bagdør" i koden, ligger den i den utestede del.

Da jeg arbejdede med test af software, viste det sig desuden, at softwaren virkede forskellig ved hver gennemkørsel, så resultatet af testen var forskellig hver gang. Så kom spørgsmålet, om vi skulle angive det værste vi havde set, eller det bedste vi havde set - eller bare køre testen éen gang, og vælge denne.

  • 0
  • 0
Jesper Østergaard Jensen

Kender I det, når man har en samtale med folk som putter så mange fagord ind i samtalen for at skjule, at de ved meget lidt om det de taler om og for derved at lyde så kloge, at folk ikke stiller spørgsmålstegn ved det de siger.

Sådan har jeg det lidt med folk, der ikke vil skrive kommentarer. Jeg er enig at kommentarer som:

int i; // Declare vars

ikke er noget værd. Men skriver man gode kommentarer bliver man nøjagtig som i en kravspecifikation eller problemformulering tvunget til at tænke lidt mere over sin kode. Ved at skrive kommentarer udstiller man også sig selv lidt, hvilket jeg oplever nogen er bange for, tænk hvis man skrev noget forkert og en kollega så det - så er det bedre ikke at skrive noget og se ud som om man har styr på det...

Jeg synes også, at jeg genkender hvad Therese Hansen siger om, at nogle mænd er stolte af deres komplicerede kode. Det er efter min mening en helt forkert vej at gå. Er det en angst for at blive overflødig, hvis andre også kan finde ud af ens kode og man ikke ses som den store troldmand mere? Jeg mener personligt, at man bør stile efter, at det er så nemt som muligt for andre at overtage eller rette i ens kode. Det er bedre evolution som kan bringe os alle sammen fremad.

  • 0
  • 0
Jacques d'biann

Det synes jeg specielt skinner igennem i open source udvikling hvor der netop er mange øjne/sind der potentielt skal arbejde med samme kode. Manglende kommentarer gør at folk istedet ofte bliver VED med at genopfinde hjulet, frem for at sætte sig ind i noget egnet, allerede eksisterende kode og hjælpe med at gøre det færdigt istedet.

Koden er ofte ikke så selvforklarende som subjektet SELV synes det er. Jeg har ikke tal på alle de gange hvor jeg har overvejet at kontribuere til et projekt og har droppet det igen, fordi koden bare ikke var velkommenteret nok. Og spørger man? Så bliver man ofte mødt med en selvsofistikerende elitært - ofte indbildsk bedrevidende stil, man ikke gider at beskæftige sig med alligevel.

Folk er nødt til at fatte, at kodestil som udtryk for overvejelser ud i logisk konstruktion, ofte er ekstremt idiosynkratisk og dermed meget subjektivt. Er man ikke villig til at hjælpe sin egen kode ud i et mere objektivt forståeligt univers, med den rette mængde oplysende kommentarer, de rigtige steder, så kan man heller ikke forvente at andre gider at sætte sig ind i det, for at kontribuere til dets's færdiggørelse.

Postulat: Open source udvikling ville gå- og stå 300% stærkere, med en langt mere veludviklet kommentarkultur.

  • 0
  • 0
Log ind eller Opret konto for at kommentere