Para comentarios sobre el control de versiones, ¿qué hacen / recomiendan otros usuarios: tiempo pasado o presente?

Es decir

• Cambiado x para ser y.
• o
• Cambiando x para ser y.

Los comentarios deben leerse en contexto, entonces:

Presente

Para comentarios de origen sobre un método, o antes de que ocurra algún comportamiento:

// This function does X
function doX() { ... }

Pasado

Para comentarios de origen después de que ocurriera algún comportamiento

function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ...
}

Y para enviar mensajes

la función X cambió

Ejemplo mixto:

// This function does X
function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ....
}

Pasado : dado que cualquiera que lo lea en el futuro se referirá al acto del cambio como sucedió en el pasado.

Redactar algo como "Cambiar" implica que usted está actualmente en el proceso de hacer el cambio y que el código puede no estar terminado.

nota: Personalmente, solo pongo comentarios de cambio cuando se produce un cambio drástico.

Los comentarios son cosas estáticas, por lo que deben presentar el estado del programa tal como está y no como va a ser. Para responder a su pregunta específica, sería más apropiado usar el tiempo pasado .

Sin embargo, este tipo de comentario se adapta mejor a su sistema de control de versiones. El control de versiones hace un trabajo mucho mejor de seguimiento de cambios que los comentarios manuales. Con los sistemas de control de versiones, es más apropiado documentar en tiempo presente ya que esos comentarios se aplican en el momento en que se confirma el cambio. Pero, cualquiera funcionará.

Recomiendo encarecidamente que los únicos comentarios en su código sean los necesarios para comprender el código en sí mismo: el propósito, la lógica comercial y los casos excepcionales. Deje la documentación del conjunto de cambios a su sistema de control de versiones. Si no está utilizando un VCS, comience ahora. Hay varios VCS de alta calidad que son gratuitos (Subversion, Mercurial, Git, etc.).

Uso el tiempo presente imperativo, así que algo como:

Cambia "x" por "y"

Esto es recomendado por los desarrolladores de Git:

• el cuerpo debe proporcionar un mensaje de confirmación significativo que:
  • usa el imperativo, tiempo presente: "cambio", no "cambio" o "cambios".

Puede parecer un poco extraño al principio, pero si piensa en un commit como un parche que hace algo, tiene más sentido. (Esto es especialmente cierto en un DVCS como Git, donde extrae conjuntos de cambios de otras personas que actúan en su repositorio).

Realmente no importa; Creo que es estilo personal y preferencia. Al escribir casi cualquier cosa, solo sea ​​coherente consigo mismo y con otros comentarios.

Los comentarios de código deben ser naturales para leer.

Si está leyendo el código diciéndose a sí mismo "Este código está haciendo X", entonces debe escribir el comentario en tiempo presente, ya que es probable que también piense así alguien que lea el código en ese momento. Si, por otro lado, está pensando en un punto en particular "Este código hizo X", entonces debería estar en tiempo pasado. Al final, todo se reduce a la preferencia personal, a menos que por alguna razón esté bajo pautas sobre cómo comentar su código (es decir, para un proyecto de equipo o para una clase, etc.).

Si está usando git, la convención es usar el tiempo presente porque los mensajes de confirmación generados con las herramientas git (por ejemplo, fusionar) usan el tiempo presente.

Deberías usar el tiempo pasado.

La razón es que estás respondiendo a la pregunta ¿qué logró este compromiso? Piense que le dice a su VCS lo que hizo:

Confirmar 123
XYZ cambiado para hacer ABC

Para dar ejemplos contrarios, usar el tiempo futuro hace que parezca que le estás pidiendo a alguien que lo haga:

Comprometer 123
Cambiar XYZ para hacer ABC

y usando el tiempo presente suena como si estuvieras a mitad de camino:

Compromete 123
Cambiando XYZ para hacer ABC

Use el tiempo presente: "Cambiar X a Y", casi como si fuera un elemento en una lista clara de TODO.

En general, al igual que un guión, evita verbos como "ser" y "es". Por ejemplo, no es "él está caminando", sino "él camina".

Pero en este ejemplo en particular, si está hablando de comentarios de código y no comentarios de check-in, creo que "Cambiar X a Y" es un comentario terrible. No agrega información nueva, y si el código cambiara, incluso podría ser incorrecto. Es mejor si extrae el código en un método (o una clase) y luego documenta ese método. Si es lo suficientemente claro, solo un buen nombre de método será suficiente.

Hablando de eso, para documentar métodos, podría usar el tiempo futuro, por ejemplo: "Si el número proporcionado es negativo, absdevolverá la magnitud del número".

Los comentarios son (o deberían ser), como cualquier cosa escrita, expresiones de algo, y simplemente deben seguir las mismas reglas en lenguajes naturales (teniendo en cuenta las abreviaturas y abreviaturas específicas de la situación o el artefacto que se está documentando.

Los comentarios sobre el tiempo presente ( es decir, "cambia" o "está cambiando" ) indican que un dato que está siendo operado por el algoritmo documentado está siendo afectado de alguna manera. Es decir, indica qué está haciendo el código o qué está ocurriendo con los datos que se manipulan.

Los comentarios en tiempo pasado deben indicar una afirmación, condición previa o condición posterior de algo que ha sucedido antes del punto donde reside el comentario. Por ejemplo:

La entrada ya ha sido validada antes de ingresar este bloque de código

o

Los datos se escribieron en el archivo al final de este código que se está ejecutando

Los comentarios en tiempo pasado también pueden explicar por qué se está haciendo algo ( esta función hace X e Y para tratar un problema con la base de datos heredada ) .

Los comentarios en tiempo pasado que indican un cambio en el código en sí (es decir, X se cambió a Y ) no deberían existir en el código. En su lugar, deberían existir como comentarios de revisión en el repositorio de código fuente.

Los comentarios en el futuro deben indicar una condición que debe cumplirse o abordarse, pero que por razones X o Y no se está haciendo en este momento. Por ejemplo:

Cuando finalmente migremos la base de datos, tendremos que cambiar esta lógica

o

TODO: lo antes posible, vuelva a validar la entrada: puede fallar para el tipo de entrada X o Y, puede requerir cambios masivos que no se pueden implementar en este momento.

Para el tipo de comentarios TODO posterior , debe existir alguna otra forma de documentación para asegurarse de que tales cambios realmente tengan lugar. Lo último que quiere son TODOS perdidos en tiempo y espacio: P

Tómelo con un grano de sal, pero generalmente esas son las reglas que generalmente sigo cuando hago mis propios comentarios.

Los comentarios se refieren a la comunicación con los seres humanos, por lo que si bien la coherencia es importante, es importante no empantanarse en principios cuando los principios mismos se interponen en el camino de la buena comunicación. Dicho esto, uso los siguientes pseudo-estándares:

• Los comentarios que describen un comportamiento deseado toman la forma de una oración imperativa en tiempo presente.

  // Calculate the width of the curve at x height.
  

• Utilice un conjunto de palabras clave en mayúsculas para describir temas comunes en la codificación (y para facilitar la búsqueda):

  // NOTE: <This code was written this way for a reason.>
  // TODO: <This code is incomplete. Finish it.>
  // HACK: <This code was written this way for a reason that you won't like.>
  // FIXME: <This code has a known flaw. Fix it.>