Stile della documentazione: come si differenziano i nomi delle variabili dal resto del testo all'interno di un commento?

Question

Questa è una domanda superflua e poco interessante, temo, ma mi chiedo sempre. Quando commentate il codice con commenti incorporati (al contrario dei commenti che appariranno nella documentazione generata) e il nome di una variabile appare nel commento, come lo differenziate dal testo normale? Es .:

// Try to parse type. 
parsedType = tryParse(type); 

Nel commento, "tipo" è il nome della variabile. Lo segna in qualche modo per significare che è un simbolo e non solo parte del testo del commento? Ho visto cose del genere:

// Try to parse "type". 
// Try to parse 'type'. 
// Try to parse *type*. 
// Try to parse <type>. 
// Try to parse [type]. 

E anche:

// Try to parse variable type. 

(non credo che l'ultimo è molto utile, è un po 'di confusione, si potrebbe pensare "variabile" è un aggettivo lì)

Avete qualche preferenza? Trovo che ho bisogno di usare qualche tipo di pennarello; altrimenti i commenti sono a volte ambigui, o almeno ti costringono a rileggerli quando ti rendi conto che una particolare parola nel commento era in realtà il nome di una variabile.

(Nei commenti che appariranno nella documentazione che uso i tag appropriati per il generatore, naturalmente: @code, <codice> </code >, ecc)

Grazie!

Answer 1

QUALSIASI di questi stili che lei ha citato, a patto che non v'è coerenza tutta la documentazione.

Answer 2

99,9% del mio tempo che sto facendo PHP, in cui questo problema doen't esistere:

// Try to parse $type. 

ma quando faccio un po 'di roba in altre lingue, mi piace virgolette singole (ma penso che non è molto importante quello che si utilizza, ma si consiglia di utilizzare lo stesso ogni volta, non cambiando in ogni commento;)):

// Try to parse 'type'. 

Answer 3

nell'esempio fornito, il commento in combinazione con la riga di codice che è essere commentato fornisce tutto il contesto richiesto per capire cosa è stato scritto.

Infatti, anche quando si ha a che fare con un commento che serve a spiegare un blocco di codice, di solito non sarà un problema - code + comment = context for understanding.

Ciò detto, e come qualcun altro ha menzionato: fintanto che sei coerente, qualsiasi metodo tu scelga funziona.