Estilo de documentación: ¿cómo se diferencian los nombres de variables del resto del texto dentro de un comentario?

Question

Esta es una pregunta bastante superflua y poco interesante, me temo, pero siempre me pregunto sobre esto. Cuando comente un código con comentarios en línea (a diferencia de los comentarios que aparecerán en la documentación generada) y el nombre de una variable aparece en el comentario, ¿cómo lo diferencia del texto normal? Por ejemplo:

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

En el comentario, "tipo" es el nombre de la variable. ¿Lo marcas de alguna manera para indicar que es un símbolo y no solo una parte del texto del comentario? He visto cosas como esta:

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

Y también:

// Try to parse variable type. 

(no creo que el último es muy útil, es un poco confuso, se podía pensar "variable" es un adjetivo allí)

¿Tiene alguna preferencia? Encuentro que necesito usar algún tipo de marcador; de lo contrario, los comentarios a veces son ambiguos, o al menos te obligan a volver a leerlos cuando te das cuenta de que una palabra en particular en el comentario era en realidad el nombre de una variable.

(En los comentarios que aparecerán en la documentación de uso de las etiquetas apropiadas para el generador, por supuesto: @code, < código > </Código >, etc)

Gracias!

Answer 1

CUALQUIER de estos estilos que usted mencionó, siempre y cuando haya consistencia en su documentación.

Answer 2

99,9% de mi tiempo estoy haciendo PHP, donde existe este problema doen't:

// Try to parse $type. 

pero cuando lo hago un poco de materia en otros idiomas, me gusta comillas simples (pero creo que no es muy importante lo que se utiliza, pero se debe utilizar el mismo cada vez, sin cambiar en cada comentario;)):

// Try to parse 'type'. 

Answer 3

en el ejemplo, el comentario se combina con la línea de código que es ser comentado proporciona todo el contexto requerido para comprender lo que se escribió.

De hecho, incluso cuando se trata de un comentario que pretende explicar un bloque de código, generalmente no va a ser un problema - code + comment = context for understanding.

Todo lo dicho, y como alguien más mencionó: mientras seas consecuente, cualquiera de los métodos que elegiste funciona.