¿Qué piensa sobre los períodos / paradas completas en los comentarios de código? [cerrado]

Vi esto en la taberna SO , así que publico la pregunta aquí. Me pareció una pregunta interesante. (Por supuesto, no pertenece a SO, pero creo que está bien aquí).

¿Agrega puntos (o, como escribió el OP, "paradas completas") en los comentarios de su código?

Para mantenerlo relevante, ¿por qué ?

El punto final es para terminar las oraciones, pero si un comentario consiste en una sola oración rodeada de código, entonces, en mi opinión, no es necesario el punto final. A veces ni siquiera escribo en mayúscula la primera letra. Un comentario multilínea detallado, por otro lado, necesita puntuación completa.

// This function returns an average of two integers. Note that it may
// return an irrelevant result if the sum of a and b exceeds the int
// boundaries.

int avg(int a, int b)   // make it static maybe?
{
    // A better algorithm is needed that never overflows
    return (a + b) / 2; 
}

Sí, porque los comentarios están en inglés, y el inglés adecuado utiliza la puntuación.

¿Agrega puntos (o, como escribió el OP, "paradas completas") en los comentarios de su código?

Para mantenerlo relevante, ¿por qué?

Por la misma razón, los agrego cuando escribo texto "normal": son parte del lenguaje escrito y no deberían tener nada de especial. Los uso por igual cuando escribo comentarios de una oración (una línea) y párrafos completos.

El código fuente no es texto normal y, por lo tanto, usamos diferentes reglas para ello. Simple ;-)

Si escribe comentarios, uno esperaría que estén escritos en inglés. Siendo ese el caso, uno debe puntuar adecuadamente. Hacer lo contrario sería vago.

Si escribo una oración completa (o más), entonces sí. Si no lo hago, a veces no, pero usualmente sí.

A veces también me vuelvo loco y uso signos de exclamación, signos de interrogación, etc.;)

En cuanto a por qué, es en parte porque simplemente soy así de particular y en parte porque encuentro que la puntuación adecuada puede agregar mucha claridad.

Las otras respuestas y su popularidad han dejado en claro que los puntos completos son muy apreciados en los comentarios más largos, y probablemente se pueden evitar en una sola frase.

Otro punto que podría ser relevante es evitar los signos de exclamación, especialmente los múltiplos . Ejemplo:

    // Though loop is labor-intensive, performance is fine with with 95K cases!!!

y

    // This code really sucks!

Por otro lado, los signos de interrogación son bastante útiles a veces:

    // TODO: What does Crojpler.bway() actually do?

Depende. Si escribo un párrafo grande y apropiado que explique lo que hace un bloque de código, entonces lo puntúo correctamente, como cualquier otro escrito apropiado. OTOH, cuando solo comento una sola línea de código, entonces no lo hago.

¿Por qué? - Similar a por qué escribo correos electrónicos con la escritura adecuada, mientras que podría usar oraciones abreviadas en mensajes SMS. En un caso, me siento a escribir un bloque de texto apropiado, así que automáticamente "lo hago correctamente", mientras que en el otro es solo una breve nota para transmitir un punto.

Ejemplos reales de mi código:

Comentario de nota rápida:

// check for vk_enter

Documentación del método "apropiado":

// This method sets up a workspace tab with the given name. Each MDI window has a parent
// workspace specified when it's saved. The code which loads each MDI window then point it to
// the correct workspace.

Sí, creo que de esta manera creas una buena convención de codificación y también crea un código legible para una tercera persona que revisa tu código.

Yo siempre capitalizar adecuadamente y marcan la hora de crear los comentarios XML que espero ser visto en IntelliSense y en nuestra documentación generada . Estas son construcciones mucho más formales y deben tratarse como tales.

Sin embargo, los comentarios que se acaban de ver en el cuerpo de un bloque de código deberían ser tan claros como sea posible. Depende del programador cómo logran eso.