Stor nytta med historisk Unix version 6 från 1975

[kodar-holger]

bra skriven kod är självdokumenterande

Det här är något av det dummaste som någonsin sagts om kommentarer. Jag hävdar att det går aldrig att skriva kod som är så bra att den i sig förklarar varför den gör som den gör. För det är just det som är poängen med kommentarer. Man skall dokumentera varför koden ser ut som den gör. Inte vad den gör. Alla som följer detta borde få plikta med att få backspace disablat.

[hcb]

Vad säger du om `Literal Programming'?

(Nej, jag dörjar inte, jag är genuint nyfiken.)

[TomasL]

Kan inget annat än att hålla med kodar-holger, Kod SKALL vara noggrant dokumenterad, till varje funktion SKALL det finnas en noggrann beskrivning vad den gör osv.
Världens mest buggfira kod, där tar dokumentationen och kommentarerna upp typ 10-20 ggr mer plats än koden i sig, i princip varje kodrad är motiverad , (koden till rymdskyttlarna)

[sodjan]

Det här är mitt favoritexempel på "dokumenterad" kod. Det är mer
en manual/tutorial for USART som även kan köras direkt i MPASM.
Den är för en utgången PIC modell, men väldigt välgjort...

http://www.piclist.com/images/com/frees ... icuart.asm

[lillahuset]

Ett problem med väldokumenterad kod är att man ibland läser komentarerna som beskriver vad som bör ske men att någon har ändrat koden så något annat sker. Det är inte alltid dokumentationen beskriver verkligheten. Vilket den naturligtvis ska. Men vi är ju alla pajasar då och då.

[TomasL]

Då är den per natur inte väldokumenterad.
Varje förändring skall dokumenteras med orsak och verkan , mm

[sodjan]

Jag jobbar med kod som är över 30 år gammal och som har haft löpande
småändringar under alla år. Där får man verkligen kolla koden ordentligt
för att se *vad* som händer. *Varför* den gör det den gör kan man oftast
glömma, de som visste det är sedan lång tid på andra jobb eller i pension.
Koden från de senate 8 åren (den tid jag har varit med) är ganska OK
att förstå...

[lillahuset]

Jodu TomasL, vilken planet kommer du ifrån? Eller är det så att du är en fjunig fjortis?

[MiaM]

Ett problem med väldokumenterad kod är att man ibland läser komentarerna som beskriver vad som bör ske men att någon har ändrat koden så något annat sker. Det är inte alltid dokumentationen beskriver verkligheten. Vilket den naturligtvis ska. Men vi är ju alla pajasar då och då.

Man måste ha en policy som tillåter folk att bara helt enkelt göra tillägg som säger att kommentarerna har fel, utan att förklara exakt vad. Annars kommer folk bara ändra koden så att kommentarerna är fel utan att nämna det...

[lillahuset]

I den värld jag har verkat har det aldrig fungerat.

[jpalsson]

Det här är mitt favoritexempel på "dokumenterad" kod. Det är mer
en manual/tutorial for USART som även kan köras direkt i MPASM.
Den är för en utgången PIC modell, men väldigt välgjort...

http://www.piclist.com/images/com/frees ... icuart.asm

Snyggt exempel !

Ex, att få veta det som kommentaren nedan berättar kan ju spara en del tid.

Kod: Markera allt

  ;GOTCHA! If you are using a MAX232 or similar device that uses
      ;charge pumping, you might want to place a delay routine
      ;right HERE to ensure that the charge pump voltage has risen
      ;to its proper operating level before any actual RS232
      ;level i/o is attempted! 

[TomasL]

Jodu TomasL, vilken planet kommer du ifrån? Eller är det så att du är en fjunig fjortis?

Den kommersiella världen, där vi försöker tjäna maximalt med pengar på våra produkter.

Sodjans länk visar hur man skall göra, att sedan formatera det hela för DoxyGen, eller liknande är naturligtvis ett krav också.

[sodjan]

Ja, jo, även om det är ett lite extremt exempel. Det är lika
myckt en kurs i hur PIC USART fungerar som ren kod. Om man
förutsätter vissa grundkunskaper så hade det nog inte blivit
riktigt lika fylligt med text i exemplet...

[TomasL]

Förvisso, men om man kommenterar på det sättet blir det extremt enkelt för nästkommande utvecklare att sätta sig in i koden, samt eventuellt buggrättande underlättas radikalt.
Just det här med att inkorporera HW-errata och liknande är naturligtvis ett måste.

[jpalsson]

Den kommersiella världen, där vi försöker tjäna maximalt med pengar på våra produkter.

Sodjans länk visar hur man skall göra, att sedan formatera det hela för DoxyGen, eller liknande är naturligtvis ett krav också.

Jag tror att många faller i den fällan att man tänker "Äsch, jag slänger ihop det här, det här systemet ska inte leva så länge".
Och, i och med det tankesättet så tar man inte heller betalt för att sitta och dokumentera (eller testa för den delen).

Sen visar det sig att systemet trots allt fortsätter att leva år efter år och till slut när ingen längre kommer ihåg något
om programmet och de personer som ursprungligen var involverade inte längre är kvar, då blir det ett problem.

Jag gillar Sodjans exempel, det finns en hel hög med "Gotchas" i koden som förklarar knepigheter
där processor och omgivande elektronik inte kanske beter sig som en programmerare skulle tro.
Mycket handlar ju om förkunskaperna hos dem man sätter koden i händerna hos.

Däremot så pekar ju Sodjan också ut ett annat problemområde, nämligen "varför gör koden så här", dvs. affärsregler.
Det här är ju så mycket lurigare eftersom man till slut (efter lite personalomsättning) kan hamna i en situation där
ingen riktigt vet varför ett kodavsnitt finns där.
Ex. vem har bestämt att jämna ordernummer ska ges 3% rabatt på en viss artikelgrupp ?
Dvs. koden kan vara tekniskt helt perfekt, testad och buggfri men ändå fel sett till hur företaget vill bedriva sin verksamhet.

/Johan