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

27

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é ?

Moshe
fuente
2
A veces lo hago y a veces no. Depende de los comentarios y de lo que facilita su lectura.
Tim

Respuestas:

29

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; 
}
mojuba
fuente
44
+1. Esto se parece tanto a mi estilo de comentario que me dio un falso deja vu. :)
Bobby Tables
26
No, el punto final es para marcar el final de las oraciones. Es irrelevante si tiene uno o varios.
Torre
2
<joke> ¿No sería mejor verificar si se superan los límites int? </joke>
Dan Rosenstark el
2
@Yar: un promedio siempre está entre ayb, que por definición siempre están dentro de los límites, ¿verdad? ;)
mojuba
8
Todas mis cadenas están terminadas en nulo, por lo que un comentario adecuado siempre debe terminar con '\ 0'. ¿No quieres que el siguiente tipo que mira tu código lea más allá de su mente, verdad?
CodexArcanum
26

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

Dominique McDonnell
fuente
2
¿Qué hay de los mensajes de texto?
Moshe
44
@ Moshe, los mensajes de texto no son el inglés adecuado.
Dominique McDonnell el
8
Inglés apenas apropiado, pero todavía uso la puntuación en ellos. La puntuación está ahí para guiar al lector en cuanto a lo que pretendía exactamente el autor; esto se aplica a cualquier idioma, en mi humilde opinión.
cjmUK
@cjmUK, Lol, sí, y yo también. Pensé que Moshe lo decía como una razón por la que no usaríamos la puntuación, ya que regularmente recibo mensajes como "ese wd b gr8 cu there bye" que me llevan por la pared
Dominique McDonnell
No puedo
decirte que voy a estar
17

¿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 ;-)

Torre
fuente
Un amigo mío nunca capta palabras en correos electrónicos ... porque está en Internet. Para mí está bien cuando adaptas tu escritura a limitaciones técnicas como los SMS, pero ¿en qué se diferencian los correos electrónicos o el código fuente del texto en cartas y libros?
LennyProgrammers
1
@ Lenny222 - No estoy seguro de lo que estás preguntando aquí. Los correos electrónicos deben escribirse como texto normal; como si estuvieras escribiendo una carta como dices. Cómo se escriben en realidad (y los SMS, oh chico, no me hagas comenzar con los SMS :) El código fuente no se somete a las mismas reglas que el texto normal, porque tiene sus propias reglas de sintaxis.
Torre
2
Para mí, los comentarios del código fuente están destinados a ser leídos por seres humanos. ¿Por qué debería hacer una diferencia si alguna información está en un documento de especificación separado o incrustado en un comentario de código fuente?
LennyProgrammers
@ Lenny222 - Algo me ocurrió, así que para que no haya malentendidos entre nosotros. ¿Ahora estamos hablando del código fuente o de los comentarios incluidos en él? Si es el segundo caso, me disculpo, porque te he entendido mal. En ese caso, se aplican las mismas reglas que para el texto normal (para comentarios). En el código fuente real (el que lee el compilador / intérprete), no veo cómo podrían seguir las mismas reglas.
Torre
1
Sí, creo que estamos de acuerdo sin saberlo. ;)
LennyProgrammers
9

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.

rápidamente_ahora
fuente
1
Los períodos son para el final de una oración. Los comentarios no son necesariamente oraciones completas.
John B. Lambe
Los comentarios, en general, deben ser oraciones. Si no, debería preguntar por qué no. Si sus comentarios son tan cortos que no son oraciones, ¿son quizás obvios y, por lo tanto, superfluos?
rapid_now
5

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.

Adam Lear
fuente
Si usa signos de interrogación, ¿comprende su propio código?
Moshe
@Moshe: Por lo general, están en TODO cuando aún no entiendo completamente mi propio código.
Adam Lear
2
@Moshe - ¿Por qué los comentarios no pueden incluir preguntas? Las preguntas pueden ser retóricas. De hecho, a menudo nosotras? en mis comentarios, cuando describo el código condicional, en lugar de una explicación seca de la lógica, a menudo es más claro describir la lógica como una pregunta. Por ejemplo, "¿Se han cumplido los criterios de calificación? En caso negativo, mostrar advertencia al usuario".
cjmUK
1
Al trabajar con grandes proyectos y muchos colaboradores, a menudo encuentro esos comentarios de preguntas más importantes.
LennyProgrammers
3

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?
Dan Rosenstark
fuente
1

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.
Mesas Bobby
fuente
Desarrollador .NET, ¿eh? ;-)
Moshe
@Moshe: Java en realidad. Este es el código de un applet muy grande y complejo, básicamente como una aplicación Swing de escritorio, excepto que se ejecuta en el navegador. :)
Bobby Tables
Pensé que MDI es un término .NET.
Moshe
@ Moshe: No, es genérico ( en.wikipedia.org/wiki/Multiple_document_interface ).
Bobby Tables
1

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.


fuente
1
¿Qué hay de una segunda persona?
daviewales
0

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.

Matt DiTrolio
fuente