Si tratta di una buona pratica di documentazione del codice?

Naviga le tue risposte
3

Sto lavorando su 2 progetti projA e projB , ed entrambi i progetti sono progetti di manutenzione. Per projA ci sono 3 programmatori e per projB ci sono 2 programmatori. In ogni caso tutti stanno lavorando su punti separati.

Dato che la documentazione del codice è molto importante, puoi dirmi qual è la pratica migliore?

Esempi: 

  {Author : lee    -verion 1.7    -date 30 dec  -asked by someGuy  -decription: to antialiase a line}   
  procedure antiAlias(thisline);
  begin
     //do the anti aliasing...
   end;

o 

   {*123}
  unit testone;
..
..
..

    procedure antiAlias(thisline);
  begin
     //do the anti aliasing...
   end;
..
..

 end. //end of the unit..

{*123}
  {Author : lee    -verion 1.7    -date 30 dec  -asked by someGuy  -decription: to antialiase a line}

il {*123} rappresenta il punto che ho fatto per la particolare unità. Quindi il prossimo punto {*124} sarà alla fine dell'unità.

Questo è fatto (molto raramente) dato che il codice sembra pulito senza la parte commentata e un sacco di decription alla fine.

    
posta PresleyDias 30.12.2011 - 18:48
fonte

3 risposte

8

Personalmente non mi piacciono entrambi gli approcci. Ad eccezione della descrizione (che idealmente avrei prima del metodo, ad esempio il primo esempio), gli altri dettagli aggiungono inutili confusione al codice, questo è il significato dei registri di controllo e di commit del codice sorgente.

    
risposta data 30.12.2011 - 18:56
fonte
6

Basta commentare cosa fa e perché - le cose che il programmatore che ha corretto il codice deve conoscere e non possono ottenere leggendo il codice.

Chi, dove, quando, ecc. possono ottenere dai commenti sul controllo SVN / GIT / etc

    
risposta data 30.12.2011 - 19:00
fonte
6

Non è necessario tracciare la cronologia delle revisioni nei commenti al codice.

La documentazione dovrebbe iniziare con nomi di entità significativi. I commenti dovrebbero espandersi su ciò che il nome e la firma ti dicono. Un metodo chiamato "antiAlias" che accetta un parametro "thisLine" non ha bisogno di un commento che spieghi che è "antialiare una linea", tanto è ovvio. Potrebbe essere utile spiegare cosa intendi con "antialias". Se il proprio ambiente supporta uno stile di commenti che appare nella guida in linea per l'entità, tale commento che documenta cosa dovrebbe usare un metodo. I commenti che documentano come funziona il codice dovrebbero apparire prima del codice descritto.

    
risposta data 30.12.2011 - 19:44
fonte

Leggi altre domande sui tag

Vale la pena imparare una lingua arcaica? [duplicare] È una buona idea generare codice con l'aiuto del tuo IDE? [duplicare]