¿Escribe comentarios en segunda o tercera persona?¿Comentarios de segunda o tercera persona?
// go somewhere and do something (2nd person comment)
o
// goes somewhere and does something (3rd person comment)
Definitivamente tercera persona estilo.
a menudo tienden a hablar de estilo médico:
// Now we take $x and check whether it's valid for this pass
Un consejo útil: tratar de mantener cada comentario como auto-contenido como sea posible. Por ejemplo, esta forma:
// First, mumble the frabbitz.
blah blah
// Second, foobar the quux
blah blah
esta es una narración muy bien, pero hace que sea más difícil para editar el código, ya que las partes "primero" y "segundo" puede llegar a ser incorrecta. Al final, no agregan mucho a los comentarios, sino que los relacionan de manera frágil.
veces me hablan en primera persona, como este
/*
Usage:
set_position(0.5, 0.5); // im in the center
set_position(0.0, 1.0); // im in the lower,left corner
*/
Esto puede depender de la cantidad de personas están editando el código y con qué propósito. En mi propio código (que, sin embargo, es de uso público), puedo agregar algunos comentarios personales, tal vez usando 'I'. En un proyecto comunitario, los comentarios deben apuntar a un estilo comunitario y el "yo" puede estar fuera de lugar.
Tenga en cuenta que los comentarios son frágiles y muchas autoridades modernas (por ejemplo, Clean Code) sugieren que las funciones y los campos deberían llevar nombres significativos. Pero, por supuesto, hay muchos lugares donde los comentarios explicativos siguen siendo vitales.
Mi opinión es que solo debe usar el estilo que le resulte más cómodo.
Los comentarios insertados están destinados a que usted y otros desarrolladores intenten comprender los detalles de implementación de su código. Mientras sean claros e inteligibles, importa si el estilo es un poco inusual, la gramática es un poco pobre o hay algunos errores de ortografía. Las personas que lo están leyendo deberían estar más allá de preocuparse por esas cosas.
Los comentarios que se extraen para formar la documentación de API merecen un poco más de atención a las sutilezas de estilo, gramática y ortografía. Pero incluso aquí la precisión y la integridad son mucho más importantes.
Tengo que estar en desacuerdo con el comentario sobre los comentarios. Para mí, los comentarios fáciles de leer son los que están bien escritos, lo que significa buena gramática, buena ortografía y buena puntuación. –
Oye, mira, también me resulta irritante ver errores ortográficos gramaticales, etc. en los comentarios. Pero lo aguantaré sin quejas. muy pocos desarrolladores son capaces de producir prosa brillante. E incluso si lo fueran, hay más cosas productivas que podrían estar haciendo con su tiempo que pulir sus comentarios. –