1. Dator och IT
  2. Systemutveckling

Kommentera kod i marginalen

Svara
2011-08-15, 12:37
  #1
gosh
Medlem
Hur vill du att koden skall vara kommenterad?

Personligen frsker jag separera kommenterar frn koden. Ogillar nr det kommer ngon eller ngra kommenteringsrader sedan kod och s vidare.

Dremot r det mycket viktigt med kommentarer, speciellt p sdant som inte r helt sjlvklart.
Variabler r ofta viktiga att kommentera, speciellt medlemsvariabler i objekt (tnker inte p loop variabler och liknande)

Bsta tekniken jag sett fr ovanstende och som jag kr sjlv r att kommentera utmed en marginal p xx antal tecken (kanske 100 tecken till hger). D kan man lsa kommenterar frst och sedan g p koden utan att den blandas.
Debugkod (fr oss C++) r ocks ngot jag frsker "gmma" till hger om denna marginal.

Funktioner mm r enklare d man dr kan skriva kommentaren ovan utan att det kladdar ner koden.

Det enda problemet jag sjlv sttt p med detta kommenderingsstt r nr man mste ndra indenteringen, och kommentaren i marginalen flyttar sig. Brukar inte vara ngot strre problem eftersom de flesta editorer kan flytta markerade block till vnster eller hger.
Citera
2011-08-15, 13:37
  #2
Nostradumbass
Medlem
Nostradumbasss avatar
Det viktiga r att man kommenterar VARFR man gr p ett visst stt, och inte HUR.
Hur framgr i koden. Men nr jag lser dina kommentarer vill jag frst varfr du har
valt att gra som du gjort. Koden kan fr mig vid frsta anblick verka t.ex. konstigt
eller ondigt tillkrnglat eller rentav hjrndtt; men om jag vet VARFR s slipper jag
gra misstag nr jag ska laga din kod.

Vart i koden kommentarerna str r skitsamma.
Citera
2011-08-15, 14:54
  #3
Kada
Medlem
Citat:
Ursprungligen postat av gosh
Personligen frsker jag separera kommenterar frn koden.

Hur menar du med "separera" kommentarer frn koden? Kommentarer mste ju sjlvklart st tillsammans med den kod som kommentaren gller, annars blir det ju hur rrigt som helst att frska frst dem.

Jag trycker bara TAB och skriver en kommentar strax till hger om ngot som behver frklaras, om det bara gller en enda rad. Om det gller flera rader s skriver jag en kort kommentar precis ovanfr raderna som fljer. Jag skriver aldrig kommentarer som r lngre n en enda rad.

Exempel:

Kod: 
long filesize(FILE *fp) {
   long offset, size;

   offset = ftell(fp);		/*	remember current position	*/
   fseek(fp, 0, SEEK_END);
   size = ftell(fp);
   fseek(fp, offset, SEEK_SET);		/*	return to previous position	*/

   return size;
}

Just den funktionen behver vl egentligen inga kommentarer, men jag anvnde den som exempel. Simpelt och rent! (enligt mig)
Citera
2011-08-15, 15:45
  #4
Aldain
Medlem
Aldains avatar
Kr sjlv p korta men mnga kommentarer, och d med respektive kommentar precis ovanfr den kodsnutt den ska frklara. Kanske r lite vertydlig ibland men det r jvligt uppskattat av folk som senare ska stta sig in i koden nr det str frklarat lite verallt p ren svenska/engelska vad koden gr och varfr.
Tycker ven om att ha ganska mycket linebreaks, anser det vara lttare att lsa n ett massivt textblock...

Kod:
/// <summary>
/// Some function.
/// </summary>
/// <returns>Some value.</returns>
private int SomeFunc()
{
    //Calculate a value to return
    int valueToReturn = 1 + 2 * 3;

    //Return the calculated value
    return valueToReturn;
} 

Mhnda r jag lite vertydlig ibland, men mina kollegor uppskattar det som sagt.
Citera
2011-08-15, 17:20
  #5
kh31d4r
Medlem
kh31d4rs avatar
Citat:
Ursprungligen postat av Aldain
Kr sjlv p korta men mnga kommentarer, och d med respektive kommentar precis ovanfr den kodsnutt den ska frklara. Kanske r lite vertydlig ibland men det r jvligt uppskattat av folk som senare ska stta sig in i koden nr det str frklarat lite verallt p ren svenska/engelska vad koden gr och varfr.
Tycker ven om att ha ganska mycket linebreaks, anser det vara lttare att lsa n ett massivt textblock...

Kod:
/// <summary>
/// Some function.
/// </summary>
/// <returns>Some value.</returns>
private int SomeFunc()
{
    //Calculate a value to return
    int valueToReturn = 1 + 2 * 3;

    //Return the calculated value
    return valueToReturn;
} 

Mhnda r jag lite vertydlig ibland, men mina kollegor uppskattar det som sagt.

Jag skulle undvika sjlvklara kommentarer, istllet fr att skriva kommentarer varannan rad s r det bttre att ge identifierare vettiga namn s att man frstr vad de r/gr (svrt i ett 100% phittat exempel kanske). Massvis av ondiga kommentarer gr bara koden kluttrig och svrlst. Gr man ngot som inte r uppenbart vad och varfr man gr det br man skriva om sin kod, och i de f fall man inte kan det r sista utvgen att skriva en kommentar (komplexa regex r inte alltid helt ltta att refactora till exempel).
Citera
2011-08-15, 17:57
  #6
Kada
Medlem
Citat:
Ursprungligen postat av Aldain
Kod:
private int SomeFunc()
{
    //Calculate a value to return
    int valueToReturn = 1 + 2 * 3;

    //Return the calculated value
    return valueToReturn;
} 

Ett problem med det hr sttet att kommentera r att det snabbt kan bli vldigt mnga rader i funktionen. Eftersom kommentarerna endast gller en enda rad kod s skulle jag hellre vilja lgga dom bredvid raden, istllet fr ovanfr. Jag brukar frska gra mitt allra bsta fr att aldrig lta en funktion verstiga en skrm i storlek i Notepad. Shr hade varit bttre (enligt mig):

Kod:
private int SomeFunc()
{
    int valueToReturn = 1 + 2 * 3; //Calculate a value to return
   
    return valueToReturn; //Return the calculated value
} 

I vrigt s hller jag med Aldain om att mnga radbyten r snyggt och ett bra stt att gra koden mer lttlslig. Men det fr inte bli fr mnga radbyten, utan de ska vara placerade endast dr de behvs. Exempel p hur jag brukar gra:

Kod: 
void init_input() {
   int i;

   SDL_EnableUNICODE(1);
   SDL_ShowCursor(SDL_DISABLE);

   for (i = 0; i < 256; i++)
      mouse.buttons[i] = 0;

   SDL_WarpMouse(mainscr->w / 2, mainscr->h / 2);	/*	center mouse pointer	*/
}

Exempel p hur jag INTE skulle gra:

Kod: 
void init_input() {
   int i;
   SDL_EnableUNICODE(1);
   SDL_ShowCursor(SDL_DISABLE);
   for (i = 0; i < 256; i++)
      mouse.buttons[i] = 0;
// center mouse pointer
   SDL_WarpMouse(mainscr->w / 2, mainscr->h / 2);
}
Citera
2011-08-15, 18:22
  #7
gosh
Medlem
exempel p att skriva kommentarer i marginalen
Kod:
.
               if( *pwszFunction == L'{' )
               {
                  pwszFunction++;                                                                  // move past {
                  const wchar_t* pwszBegin = pwszFunction;                                         // where function code starts
                  const wchar_t* pwszEnd = NULL;                                                   
                  pwszFunction = match( pwszFunction, L'{', L'}' );                                // find last position for function
                  if( pwszFunction != L'\0' ) pwszEnd = (pwszFunction - 1);
                  
                  if( pwszEnd != NULL )
                  {
                     lError = parse( pwszBegin, pwszEnd, *pexpressionFunction );                   // parse code for function into expression
                     if( lError == 0 )
                     {
                        rexpression.append( NULL, pexpressionFunction );                           // append function to expression 
                        valueInsert = pexpressionFunction;
                     }
                     else
                     {                                                                             assert( false );
                        std::wstring string( L"Function (subroutine) error - function: \"");
                        string += pexpressionFunction->get_wtext();
                        rexpression.append_error( string.c_str(), pwszPosition, pwszFunction );
                        delete pexpressionFunction;
                        return CALCULATE_E_MethodError;
                     }
                  }// if( pwszEnd != NULL ) {
               } 
Citera
Svara

Skapa ett konto eller logga in för att kommentera

Du måste vara medlem för att kunna kommentera

Skapa ett konto

Det är enkelt att registrera ett nytt konto

Bli medlem

Logga in

Har du redan ett konto? Logga in här

Logga in