Avatar billede thomas_nj Nybegynder
30. marts 2006 - 22:03 Der er 13 kommentarer og
2 løsninger

Tilpas kommenteret kode

Hej eksperter

  Jeg leger lidt med, hvordan en kode skal stilles op mht informationer, kommentarer osv.

  Sådan ud fra hvad jeg selv synes virker rimeligt er jeg kommet frem til følgende.

/*
- Filename: main.cpp

- Made by: Thomas N. Jensen

- Last modified: 30/3 - 2006

- Description: This program is the solution to the challenge at http://www.cprogramming.com/challenges/count.html The purpose of the program is to take the name of a file as an argument and if it is a valid filename print out the number of lines in the file.

- Known bugs: None
*/


#include <iostream>
#include <fstream>

using namespace std;

int main(int argc, char *argv[])
{
  // Check if there is given the right number of arguments.
  // If not the program will tell if there is to few or to many, print how to correctly use the program
  // and quit with 1
  if(argc!=2)
    {
      if(argc<2)
    {
      cerr<<"To few arguments! "; // The line will be completed further down
    }
     
      else if(argc>2)
    {
      cerr<<"To many arguments! "; // The line will be completed further down
    }

      cerr<<"Use the program like this: fileCount file.type"<<endl;
      return 1;
    }

  ifstream inFile(argv[1]); // Input file
  int lineCount=0;
  char buff[255]; // Stores the line which is being counted

  if(inFile.fail()) // Check if something is wrong with the file. Fx if it exists.
    {
      cerr<<"An error occurred while trying to open the file "<<argv[1]<<endl;
      return 1;
    }

  while(!inFile.eof())
    {
      inFile.getline(buff, sizeof(buff)); // needed to move to next line
      lineCount++;
    }

  lineCount--; // The loop above will always run once to many.

  cout<<lineCount<<endl;

  return 0;
}

1)  Koden er selvfølgelig forholdsvis simpel, men vil I mene at kommentarerne er tilpas. Der er ikke unødige eller manglende oplysninger?

2) Jeg sad og blev lidt irriteret over at while-loopet kører en gang for meget. Er der en forklaring på dette?
Avatar billede arne_v Ekspert
30. marts 2006 - 22:35 #1
headeren har vi diskuteret generelt i en anden traad

jeg kan ikke lide "last modified"

jeg foretraekker en liste med tid, bruger og forklaring paa
hver enkelt rettelse

----

og ikke for at vaere negativ men jeg kan heller ikke lide dine
kommentarer i koden

jeg synes ikke at de fortaeller meget udover det som er aabenlyst udfra
koden

char buff[255]; // Stores the line which is being counted

->

char currentline[255];

etc.
Avatar billede bertelbrander Novice
30. marts 2006 - 22:50 #2
At lave kommentarer i kode er svært, at opstille regler for kommentarer i kode er mere end svært.

Din header er ok, jeg synes heller ikke der skal være en dato på, hvis der skal være noget skal det være en historie og/eller versions indikation. Jeg kan godt lide headere der har en tydelig markering af hvornår de starter og stopper, f.ex:

/* Header
** Stuff
** More stuff
*/

Kommentarer i kode kan deles i to: kommentarer til interface og kommentarer til implementation. Den første del er vigtig den anden ikke.

Kommentarer til interface er skrevet til brugeren af koden, kommentarer til implementation er skrevet til folk der skal vedligeholde koden.

Der hvor jeg oftest kommenterer implementation er når der er noget der er uklart eller ikke helt logisk, og så er det ofte et hint om at designet er mindre pænt.

Hvis vi kikker på:
lineCount--; // The loop above will always run once to many.
Vil jeg som læser af koden hellere vide hvorfor loopen kører for længe.
Avatar billede thomas_nj Nybegynder
30. marts 2006 - 23:05 #3
arne_v >> Vil det sige at du mener at selve koden i sig selv er forklarende, hvis lige navnet på buff ændres?

  bertelbrander >> Kan ikke rigtigt finde ud af, hvorfor den kører den ekstra gang. Min eneste teori er at eof() skal bruge en form for slutmarkør for at vide at slutningen af filen er nået.
Avatar billede arne_v Ekspert
30. marts 2006 - 23:12 #4
i det tilfaelde ja

kommentarer skal kun bruges hvis de fortaeller noget som en kompetent programmoer
ikke kan se ud af koden (inkl. navne)
Avatar billede bertelbrander Novice
30. marts 2006 - 23:13 #5
Den kører en gang for meget fordi eof flaget først bliver sat når man har forsøgt at læse ud over enden på filen, ikke når den er ved enden på filen.
Din sidste getline vil fejle, men du tæller alligevel loop counteren op.

Du kan løse problemet ved at bruge:
  while(inFile.getline(buff, sizeof(buff)))
      lineCount++;

Det kunne også være interessant at få at vide (dvs. en kommentar i koden til) hvorfra tallet 255 stammer. Tal der blot står i koden unden kommentarer gør mig altid mistænksom.

Du kunne lave:
#define MAX_LINE_LEN 255

char currentline[MAX_LINE_LEN];

Dermed har du (delvist) dokumenteret hvad 255 er.
Avatar billede arne_v Ekspert
30. marts 2006 - 23:17 #6
slut paa en fil er faktisk noget grumset noget

der er 3 mulige tests:

!inFile.eof()
inFile
inFile.peek()>=0
Avatar billede arne_v Ekspert
30. marts 2006 - 23:22 #7
#define MAX_LINE_LEN 255

char currentline[MAX_LINE_LEN+1];

ellers er det potentielt vildledende dokumentation
Avatar billede strych9 Praktikant
31. marts 2006 - 16:34 #8
Nu ikke for at trænge mig på når der allerede er to C eksperter her, men jeg har læst den ultra-simple tommelfingerregel som jeg synes var meget god: Koden kan altid fortælle dig hvad og hvordan, så det er der ingen grund til at skrive. Kommentaren skal fortælle _hvorfor_. Altså hvad er der foregået mellem ørerne på programmøren da han lavede dette.
Avatar billede arne_v Ekspert
31. marts 2006 - 16:55 #9
ikke helt forkert

der kan dog godt vaere "hvad" der kraever en forklaring
Avatar billede thomas_nj Nybegynder
01. april 2006 - 16:58 #10
Eksempelvis:

  if(argc!=2)
    {
      if(argc<2)
    {
      cerr<<"To few arguments! "; // The line will be completed further down
    }
   
      else if(argc>2)
    {
      cerr<<"To many arguments! "; // The line will be completed further down
    }

      cerr<<"Use the program like this: fileCount file.type"<<endl;
      return 1;
    }

  Ok man kan kigge på outputtet til skærmen og regne ud, hvad der er galt. Men hvis nu nu sagde at programmet slet ikke skulle give noget output men derimod bare retunere en værdi vil jeg selv ikke mene at den kan gå uden en kommentar.


  Men egentlig har jeg heller ikke nogen erfaring, med at åbne mine år gamle koder og skulle til at sætte mig ind i min daværende tankegang igen. Derfor forsøger jeg at "nasse" lidt på de mere erfarne, så jeg kan undgå de dummeste fejl.
Avatar billede arne_v Ekspert
02. april 2006 - 01:17 #11
jeg tror nok at de fleste kunne gennemskue de linier uden kommentar

omend jeg godt kan følge et argument om at man bør skrive en kommentar hvis
forståelsen af noget kode kræver at man læser længere ned for at koden
kan læses sekventielt
Avatar billede thomas_nj Nybegynder
02. april 2006 - 12:45 #12
Ser ud til at det kommer til at tage lang tid at lære at få de kommentarer sat ordentligt.
  bertelbrander >> Mange tak for hjælpen.
arne_v og strych >> Også mange tak for hjælpen og gider I ikke smide et svar?
Avatar billede strych9 Praktikant
02. april 2006 - 13:13 #13
:-)
Avatar billede arne_v Ekspert
02. april 2006 - 16:10 #14
.
Avatar billede arne_v Ekspert
02. april 2006 - 16:11 #15
gode kommentarer er ligesom god design, pæn kode etc. - man er aldrig færdig
med at lære - man kan altid blive bedre - og så er det ligegyldigt om man
man programmeret i 21 dage eller i 21 år
Avatar billede Ny bruger Nybegynder

Din løsning...

Tilladte BB-code-tags: [b]fed[/b] [i]kursiv[/i] [u]understreget[/u] Web- og emailadresser omdannes automatisk til links. Der sættes "nofollow" på alle links.

Loading billede Opret Preview
Kategori
Kurser inden for grundlæggende programmering

Log ind eller opret profil

Hov!

For at kunne deltage på Computerworld Eksperten skal du være logget ind.

Det er heldigvis nemt at oprette en bruger: Det tager to minutter og du kan vælge at bruge enten e-mail, Facebook eller Google som login.

Du kan også logge ind via nedenstående tjenester