Forskjell mellom versjoner av «Hvordan skrive et godt program»

Fra mn/ifi/INF1060
Hopp til: navigasjon, søk
(Unngå tett kode)
(Kommentering)
Linje 25: Linje 25:
 
Slik koding bidrar ikke til annet enn å gjøre programmet vanskeligere å lese. Det er med andre ord en uting.
 
Slik koding bidrar ikke til annet enn å gjøre programmet vanskeligere å lese. Det er med andre ord en uting.
  
=== Kommentering ===
+
=== Kommentering ===
  
Hvordan man skal kommentere kode er ikke lett å vite alltid, men her kommer en liste over nyttige tips. Mange tenker at "Nei, kommentere koden gidder jeg ikke for jeg skjønner jo hva som skjer." Det er to problemer med denne tankegangen; 1) Andre skjønner det ikke. 2) Det skal ikke mange dagene/ukene til før du ikke skjønner det du heller.
+
Hvordan man skal kommentere kode er ikke lett å vite alltid, men her kommer en liste over nyttige tips. Mange tenker at "Nei, kommentere koden gidder jeg ikke for jeg skjønner jo hva som skjer." Det er to problemer med denne tankegangen;  
  
Det er bare en ting å gjøre; lære seg å kommentere skikkelig, og her kommer noen tips:
+
#Andre skjønner det ikke.
 +
#Det skal ikke mange dagene/ukene til før du ikke skjønner det du heller.
  
==== Dokumentér hver metode ====
+
Det er bare en ting å gjøre; lære seg å kommentere skikkelig, og her kommer noen tips:
  
Hva er denne metodens oppgave? Beskrivelsen skal være så kort og konsis som mulig. Her skal også argumenter samt retur-verdi dokumenteres. Her er Java-doc-syntax helt fint hvis man foretrekker det. Formen på forklaringen skal ikke være "Jeg gjør slik og slik". Det skal forklares hva metoden gjør.
+
==== Dokumentér hver metode  ====
 +
 
 +
Hva er denne metodens oppgave? Beskrivelsen skal være så kort og konsis som mulig. Her skal også argumenter samt retur-verdi dokumenteres. Her er Java-doc-syntax helt fint hvis man foretrekker det. Formen på forklaringen skal ikke være "Jeg gjør slik og slik". Det skal forklares hva metoden gjør.  
  
 
/*  
 
/*  
 +
 
   Takes two numbers as arguments and return their sum.  
 
   Takes two numbers as arguments and return their sum.  
 
   - arg1: First number  
 
   - arg1: First number  
 
   - arg2: Second number  
 
   - arg2: Second number  
 
   - return: The sum of the to numbers  
 
   - return: The sum of the to numbers  
*/  
+
 
 +
*/
 +
 
 
int add_numbers(int num1, int num2) {  
 
int add_numbers(int num1, int num2) {  
 +
 
     return num1 + num 2;  
 
     return num1 + num 2;  
}
 
  
==== Kommentér paragrafer ====
+
}
  
Del koden opp i logiske deler og kommenter disse.
+
==== Kommentér paragrafer  ====
  
// Verify that all numbers are positive.
+
Del koden opp i logiske deler og kommenter disse.
// Negative values are set to zero.
+
 
int i;
+
// Verify that all numbers are positive. // Negative values are set to zero. int i; int zero_count = 0; for (i = 0; i < length; i++) {  
int zero_count = 0;
+
 
for (i = 0; i < length; i++) {
+
   if (array[i] &lt; 0) {
   if (array[i] < 0) {
 
 
     array[i] = 0;
 
     array[i] = 0;
 
     zero_count++;
 
     zero_count++;
 
   }
 
   }
}
 
  
// Calculate the average of the positive numbers
+
}
int average = 0;
+
 
for (i = 0; i < length; i++) {
+
// Calculate the average of the positive numbers int average = 0; for (i = 0; i &lt; length; i++) {  
 +
 
 
   average += array[i];
 
   average += array[i];
}
 
average = average / (length - zero_count);
 
  
==== Kom til poenget! ====
+
} average = average / (length - zero_count);
 +
 
 +
==== Kom til poenget! ====
 +
 
 +
Ikke skriv mer enn det som er nødvendig for å forklare poenget.
  
Ikke skriv mer enn det som er nødvendig for å forklare poenget.
+
==== Don’t insult the reader’s intelligence  ====
  
==== Don’t insult the reader’s intelligence ====
+
Unngå å forklare selvfølgeligheter:
  
Unngå å forklare selvfølgeligheter:
+
if (a == 5) // if a equals 5
  
if (a == 5)      // if a equals 5
 
 
     counter = 0; // set the counter to zero
 
     counter = 0; // set the counter to zero
  
fclose(file);   // Closing file descriptor
+
fclose(file); // Closing file descriptor  
  
// Output space
+
// Output space printf("\n");  
printf("\n");
 
  
 
Det er bortkastet tid å skrive unødvendige kommentarer, og det gjør det vanskeligere å lese koden.
 
Det er bortkastet tid å skrive unødvendige kommentarer, og det gjør det vanskeligere å lese koden.

Revisjonen fra 1. sep. 2010 kl. 23:02

Hvordan skrive et godt og ryddig program

Det finnes utallige meninger om hvordan et godt C-program skal se ut, men enkelte retningslinjer er de fleste enige om.

Her er en liste over viktige ting å huske på (i mer eller mindre tilfeldig rekkefølge)

Unngå tett kode

Mange skriver kode uten å bruke plass, dvs. tomme linjer for å skape naturlige avgrensninger mellom kodeblokker.

Ha alltid minst én tom linje i følgende tilfeller:

  • Mellom metoder.
  • Mellom deklarasjoner av lokale variabler og den første “statement”-setningen i en metode.
  • Før en ny kode-blokk.
  • Mellom logiske oppdelinger av en metode.

Kun et statement per linje

Mange liker å bruke flere statements per linje:

if (1 == 1) {return 1;} 
else {return 0;}

Slik koding bidrar ikke til annet enn å gjøre programmet vanskeligere å lese. Det er med andre ord en uting.

Kommentering

Hvordan man skal kommentere kode er ikke lett å vite alltid, men her kommer en liste over nyttige tips. Mange tenker at "Nei, kommentere koden gidder jeg ikke for jeg skjønner jo hva som skjer." Det er to problemer med denne tankegangen;

  1. Andre skjønner det ikke.
  2. Det skal ikke mange dagene/ukene til før du ikke skjønner det du heller.

Det er bare en ting å gjøre; lære seg å kommentere skikkelig, og her kommer noen tips:

Dokumentér hver metode

Hva er denne metodens oppgave? Beskrivelsen skal være så kort og konsis som mulig. Her skal også argumenter samt retur-verdi dokumenteres. Her er Java-doc-syntax helt fint hvis man foretrekker det. Formen på forklaringen skal ikke være "Jeg gjør slik og slik". Det skal forklares hva metoden gjør.

/*

  Takes two numbers as arguments and return their sum. 
  - arg1: First number 
  - arg2: Second number 
  - return: The sum of the to numbers 
  • /

int add_numbers(int num1, int num2) {

   return num1 + num 2; 

}

Kommentér paragrafer

Del koden opp i logiske deler og kommenter disse.

// Verify that all numbers are positive. // Negative values are set to zero. int i; int zero_count = 0; for (i = 0; i < length; i++) {

 if (array[i] < 0) {
   array[i] = 0;
   zero_count++;
 }

}

// Calculate the average of the positive numbers int average = 0; for (i = 0; i < length; i++) {

 average += array[i];

} average = average / (length - zero_count);

Kom til poenget!

Ikke skriv mer enn det som er nødvendig for å forklare poenget.

Don’t insult the reader’s intelligence

Unngå å forklare selvfølgeligheter:

if (a == 5) // if a equals 5

   counter = 0; // set the counter to zero

fclose(file); // Closing file descriptor

// Output space printf("\n");

Det er bortkastet tid å skrive unødvendige kommentarer, og det gjør det vanskeligere å lese koden.

Lesbar kode

Det aller viktigste er å skrive kode som ikke trenger kommentering. Hvis man gir metoder og variabler fornuftige navn er det ofte ikke nødvendig å kommentere så mye. Kommentarer skal kun skrives når det er nødvendig, så jo mer selvforklarende koden er, jo færre kommentarer trengs.


Ikke legg all koden i main-metoden

En del legger veldig mye kode i main-metoden. main-metoden har kun en funksjon, og det er å starte programmet.

Main bør kun inneholde logikk for å sjekke kommandolinjeparametre, samt kall på metoder som faktisk skal utføre oppgavene.


Lag en Make-fil

Make-filer kan brukes til så mangt, og egner seg spesielt godt til å kompilere et program. Programmet make vil, når det kjøres, lete etter en fil ved navn Makefile i katalogen. I denne filen kan man definere metoder (kalt target) som kan kjøres.

default:
	gcc program.c -o program

Her har vi altså et target ved navn default. Ved å kjøre make, vil default kjøre kommandoen som kompilerer programmet. Det er mulig å definere flere kommandoer under hverandre.

Hver kommando i make-filen må indenteres med tab.

clean target

Vi legger til et target for å slette den kompilerte filen samt backup-filene til Emacs.

default:
	gcc program.c -o program
clean:
	rm program *~

For å kalle clean, kjører du følgende kommando:

make clean