¿Los comentarios de .net deberían comenzar con una letra mayúscula y terminar con un punto?

Question

Dependiendo de los comentarios que reciba, podría plantear este "estándar" con mis colegas. Esto podría convertirse en una regla CustomCop personalizada. ¿Ya hay uno escrito?

Por lo tanto, Stylecop ya lo dicta para summary, param y return etiquetas de documentación.

¿Crees que tiene sentido exigir lo mismo de los comentarios?

Nota relacionada: si un comentario ya es largo, ¿debería escribirse como una oración correcta?

Por ejemplo (tal vez se esforzó demasiado para ilustrar un mal comentario):

//if exception quit 

vs

// If an exception occurred, then quit. 

Si pensó - la mayoría de las veces, si uno se molesta en escribir un comentario , entonces bien podría ser informativo. Tenga en cuenta estas dos muestras:

//if exception quit 
if (exc != null) 
{ 
    Application.Exit(-1); 
} 

y

// If an exception occurred, then quit. 
if (exc != null) 
{ 
    Application.Exit(-1); 
} 

Posiblemente, uno no necesita un comentario en absoluto, pero ya que se proporciona uno, yo creo que el segundo es mejor.

Por favor haga una copia de seguridad de su opinión. ¿Tiene una buena referencia para el arte de comentar, particularmente si se relaciona con .Net?

Gracias.

Answer 1

A menudo escribo comentarios que simplemente están destinados a ayudarme a encontrar secciones de código. (También uso regiones para esto.) Por ejemplo:

// SERVER

Debido a que el IDE colorea los comentarios, que hace que sea útil a veces para tener breves comentarios como este para ayudar en las cosas que bloquean mentalmente en segmentos. Normalmente hago esto solo por una docena de líneas de código. Si es más largo, entonces un #region parece mejor.

También suelen escribir notas en mis comentarios, a veces como una referencia para mí de esta manera:

// NOTE: -273.15 is absolute zero in °C, used for a MinValue below

No es una oración gramaticalmente bello o completa, pero tiene sentido.

Donde yo tiendo a usar frases más completa, estructurada es en el resumen de mis métodos, como esto:

/// <summary> 
/// Populates the properties of a Sensor object based on 
/// the XML components of its data file. 
/// </summary> 

Aquellos que siento son más propensos a ser leído por otra persona y que ayuda a tener la verbosidad y limpia el formateo.

Answer 2

Tomarse el tiempo para escribir comentarios claros, legibles y comprensibles nunca se pierde. Cuantas veces he vuelto a leer mis propios comentarios en una fecha posterior solo para luchar por entenderlos. Las personas que escriben comentarios descuidados o mal formados a menudo aplican los mismos rasgos a su código.

Answer 3

Si el código necesita un comentario, entonces debe estar bien formado, porque la OMI probablemente exista un concepto (no trivial) que debe ser explicado.

Deben evitarse los comentarios triviales como en sus ejemplos. No agregan nada más que ruido.

Answer 4

si comenta métodos en visual studio debería considerar usar el resumen y los params en la parte superior del método. De esta forma tendrá detalles sobre el método durante la finalización del código. Aquí está un ejemplo

/// <summary> 
    /// you summary here 
    /// </summary> 
    /// <param name="param1">Describe parameter usage</param> 
    /// <param name="param2">Describe parameter usage</param> 

Answer 5

He descubierto que cuando trato de ser escrito de observaciones (es decir, frases incompletas, fragmentos), que a menudo dejan a cabo supuestos clave o palabras que realmente aclarar el significado. Me está costando dar un ejemplo concreto en este momento, lo siento.

En general, obligarse a escribir oraciones completas y correctas también lo obliga a pensar más acerca de lo que realmente está tratando de decir con el comentario. A menudo me sorprendí reconsiderando lo que realmente quiero incluir en un comentario, escribiéndolo en su totalidad.

No hay una buena razón para sacrificar la claridad en el altar de la brevedad. Alguien tendrá que entender el código en el futuro. Los comentarios son para ellos, así que hazlos fáciles de asimilar.