Ho problemi a strutturare i miei commenti al momento.
Ho sezioni principali del codice che, durante lo scorrimento del documento, voglio essere in grado di vederle.
Esempi:
This is a normal comment:
int money = 100; //start out with 100 money
-
This is a comment to emphasize a certain part of the code:
/****** Set up all the money ******/
Ma non mi piace che non sia molto pulito. Esiste un modo standard per impostare questo tipo di commento?
Di solito uso commenti top / bottom come:
/**************************************************************************
This is a critical piece of code that controls the temparature of the main
flux capacitor.
***DO NOT CHANGE THIS*** without first getting management approval
and sign-off on form 21-B
**************************************************************************/
Trovo che le lunghe code di * di solito attirino l'attenzione della gente. Se i commenti vanno a Javadoc o qualche strumento doc che supporta enfasi italic o bold (o altri), allora ne approfitto. Penso che Doxygen e NaturalDocs supportino anche l'enfatizzazione del testo dei commenti come grassetto o corsivo, ma purtroppo non è visibile come tale nel codice sorgente del genere.
Trovo che i miei commenti su più righe rientrino in una delle due categorie.
Le intestazioni delle funzioni nella mia azienda si approssimano a quanto segue
/***************************************************
*
* functionName - brief synopsis
*
* Function description
*
* RETURNS:
*
* ERRNO:
*
* CAVEATS:
*/
Le spiegazioni dei codici a più righe tendono a utilizzare il seguente formato
/*
* Sample comment content may include phrasing such as ...
* The following code does ... yada yada yada
* Note that it affects or is affected by ... yada yada yada
* The following table describes ... yada yada yada
*/
Uno degli elementi chiave che catturano l'attenzione che trovo è la colonna di sinistra di * caratteri. La riga di * caratteri aiuta a differenziare le intestazioni delle funzioni dalle spiegazioni del codice.
Hai preso in considerazione uno dei seguenti:
Ti suggerisco di utilizzare qualche formato di commento per il markup dei documenti, come Doxygen. Trovo spesso che i commenti aggiunti al codice vengano saltati. RE: il tuo commento "normale":
int money = 100; // inizia con 100 soldi
Perché 100? Questo è ciò che vuoi rispondere.
Leggi altre domande sui tag code-quality comments