[?] Commenti "professionali"

[}gu|do[z]{®©]

Ciao ragazzi.. essendo un pignolo e aspirando alla perfezione, o ciò che più si avvicina, per un progettino per l'uni (in C.. ma credo non importi molto per il discorso ).. mi ponevo due dubbi:


Come andrebbe documentata coi commenti una funzione?
Innanzitutto meglio documentarla contestualmente alla dichiarazione dei prototipi, contestualmente all'implementazione, o in entrambe i posti?

in secondo luogo come va commentata una funzione? breve descrizione di ciò che fa, dei valori ricevuti e di quello restituito... giusto? altro?

Per il resto quali altri commenti non devono assolutamente mancare (a parte quelli suoi blocchi di codice meno banali )???

Le variabili dichiarate le commento tutte o solo quelle più oscure?
tipo se ho una variabile "i" io ci metterei "contatore che server per..." mentre una variabile "pid" di tipo "t_pid" dovrebbe essere abbastanbza intuitiva..


scusate la pignoleria

[LeleFT]

Per quanto riguarda i commenti al codice prodotto, ognuno ha le proprie abitudini e un proprio "stile". Io ti propongo lo stile utilizzato dalla Sun nel commentare il codice relativo alle proprie classi. Il sorgente delle classi Java viene utilizzato per produrre la relativa documentazione, quindi i commenti sono fondamentali per produrre una buona documentazione (e credo di non far torto a nessuno se dico che la documentazione Java della Sun sia una delle più ben fatte).
Questo è il sorgente del metodo equals() della classe String:

/**
 * Compares this string to the specified object.
 * The result is true if and only if the argument is not
 * null and is a String object that represents
 * the same sequence of characters as this object.
 *
 * anObject   the object to compare this String against.
 *
 * return     true if the String are equal;
 *            false otherwise.
**/

public boolean equals(Object anObject) {
   if (this == anObject) {
      return true;
   }
   if (anObject instanceof String) {
      String anotherString = (String)anObject;
      int n = count;
      if (n == anotherString.count) {
         char v1[] = value;
         char v2[] = anotherString.value;
         int i = offset;
         int j = anotherString.offset;
         while (n-- != 0) {
            if (v1[i++] != v2[j++])
               return false;
         }
         return true;
      }
   }
   return false;
}

Ho tolto alcuni tag di formattazione utili per la creazione di pagine HTML della documentazione, però la sostanza è questa.

Puoi notare che il codice di implementazione non è per nulla commentato (questo perchè nella documentazione non viene riportato nulla a riguardo), ma io consiglio di inserire dei commenti che aiutino chi deve leggere il codice a capirne il funzionamento.

Se poi utilizzi delle classi (magari in file separati) non guasterebbe della documentazione all'inizio del file, che spieghi cosa rappresenta la classe, cosa fa e quali sono le caratteristiche principali (metodi, solitamente) che mette a disposizione, corredata magari da qualche esempio di utilizzo.

Secondo me un modo simile di commentare il codice è ideale per una più limpida comprensione.

Ciao.

[}gu|do[z]{®©]

ok.. ma nel caso del C:
main + funzioni in un unico file... che faccio?

Le funzioni come le commento? è eccessivo per ogni prototipo dire descrizione argomenti valori di ritorno..?

meglio farlo sul prototipo o sull'implementazione?

tnx

[kentaromiura]

io userei i commenti tipo c#
ovvero i commenti XML ..
esistono tool capaci di estrarli.. ti faccio un esempio

/// <summary>
/// descrizione della funzione
/// </summary>
/// <param name="StrOrderBy">parametro che indica l'ordine del dg</param>
private void CaricaDG(string StrOrderBy){
..
}

[}gu|do[z]{®©]

sì ragà... io userei anche uno che li scrive al posto mio allora..

però nel mio specifico caso (progettino per l'uni) come devo farli per farli bene senza andare a vedere cose strane..?

in altri termini: cosa non deve mancare?

[kentaromiura]

a) aggiungi prima delle funzioni a cosa servono,
i parametri da passare e cosa ritorna..
b) ogni qualparte significativa di testo andrebbe commentata
(ovvio che i=0 si spiega da solo..)

[}gu|do[z]{®©]

Originariamente inviato da kentaromiura
a) aggiungi prima delle funzioni a cosa servono,
i parametri da passare e cosa ritorna..
b) ogni qualparte significativa di testo andrebbe commentata
(ovvio che i=0 si spiega da solo..)

ok.. chiaro

ma le funzioni dove le commento? alla dichiarazione dei prototipi o all'implementazione?

[kentaromiura]

Originariamente inviato da }gu|do[z]{®©
ok.. chiaro

ma le funzioni dove le commento? alla dichiarazione dei prototipi o all'implementazione?

commenta bene l'implementazione e fai un breve commento nella dichiarazione:

void ordina(*v[]); //ordina un vettore

/*
 questa procedura ordina un vettore di interi mediante
 l' uso dell' argoritmo fagian de fagianis
 Ritorna: nulla
 Parametri:
  *v[]:vettore di interi
*/
void ordina(*v[]){
..
}

[}gu|do[z]{®©]

ok.. sì.. forse è la cosa migliore

grassie

[daniele_dll]

mmm se metti tutto in un unico file ti conviene prima dichiarare TUTTE le funzioni varie e dopo di che la main in questo modo il codice è + pulito, oltre, credo, che non fai spuntare warning al compilatore se imposti -Wall

xo, se vuoi aumentare la leggibilità puoi provare a fare

/**
* DESCRIZIONE FUNZIONE RIGA 1
* DESCRIZIONE FUNZIONE RIGA 2
*
* @param TIPO_PARAM __TAB__ NOME_PARAM __TAB__ DESC_PARAM
* @param TIPO_PARAM __TAB__ NOME_PARAM __TAB__ DESC_PARAM
* @param TIPO_PARAM __TAB__ NOME_PARAM __TAB__ DESC_PARAM
*
* @return TIPO_RETURN __TAB__ DESC_RETURN
*/

cosi credo sia estremamente + leggibile
anche + schematico se vogliamo dire, e comunque facilmente parsabile da un qualsiasi tool di documentazione
(è quasi lo stesso stile usato nel pear, ma è ottimo

e poi se vuoi un consiglio...so che il codice diventa immenso...ma dentro il codice commenta usando

/**
* Questo fa Quest'altro
*/
il codice diventa moltooooooooo + leggible anche xche tra una riga di codice e l'altra c'è + spazio e quindi meno confusione e comunque puoi spiegare cosa fa il tutto senza attakkare il commento alla riga di codice subito sotto