Tengo una pregunta que relaciona la programación y el idioma inglés: si se debe utilizar en tercera persona o imperativo al comentar líneas únicas de código. Asumir siguiente línea de código en un lenguaje imperativo que debe ser comentó:Estilo de comentario: Imperativo o tercera persona
object.doSomething();
Mi acercamiento a comentar esta línea sería la de poner el comentario detrás de él usando la tercera persona como esta sería una sentencia de Inglés ordinaria que contiene la línea de como sujeto:
object.doSomething(); // does (referencing to the line of code) some action
Pero ya que estamos en un lenguaje imperativo y por lo tanto en realidad "al mando" del equipo, uno podría incluso pensar en poner el comentario antes del código y el uso imperativo:
//Do some action:
object.doSomething();
Esto es incluso útil cuando hay que comentar varias líneas relacionadas entre sí.
Personalmente prefiero el primer estilo pero a menudo no estoy seguro sobre qué estilo usar. Sería genial si alguien pudiera escribir su experiencia personal aquí.
Lugar incorrecto para preguntar. Los comentarios no deben ser una reformulación del código. Hay libros enteros dedicados a la legibilidad del código. –
Si necesita comentar sobre la intención del código en el nivel de línea y no es un código de máquina, ¡tiene mucho más problemas que el tiempo verbal! Mi experiencia personal es que las personas que instituyen prácticas de comentario insanas, nunca mantienen los comentarios .... –
@BasileStarynkevitch: Mantuve los ejemplos simples para mejorar la abstracción y la legibilidad de esta pregunta. No asumo comentarios para reformular el código como lo hacen aquí, sino para entrar en detalles. ¿Dónde sería el lugar correcto para preguntar ?; No veo el foro de inglés de la adaptación de StackExchange porque, en mi opinión, esta pregunta está muy relacionada con la codificación. – Paranaix