"I", "We", o Ninguno en la documentación del código

41

Me encuentro escribiendo (con suerte) comentarios útiles en el código (C ++) documentación del tipo:

The reason we are doing this is...

La razón por la que uso "nosotros" en lugar de "yo" es porque escribo muchos textos académicos donde a menudo se prefiere "nosotros".

Así que aquí está la pregunta. ¿Existe una buena razón para preferir uno sobre el otro en el código de documentación:

  1. Use "Nosotros": la razón por la que estamos haciendo esto es ...
  2. Usar "I": la razón por la que hago esto es ...
  3. Usar mi nombre: El motivo [my name] hizo esto ...
  4. Voz pasiva: la razón por la que se hizo esto es ...
  5. Ninguno: Haz esto porque ...

Elijo el # 1 porque estoy acostumbrado a escribir de esa manera, pero la documentación no es para el escritor, es para el lector, por lo que me pregunto si agregar el nombre del desarrollador es útil o si simplemente agrega otra cosa. que debe modificarse al mantener el código.

    
pregunta Alan Turing 15.03.2013 - 19:42

6 respuestas

77

Iría con:

# 6. Declarativo: ...

En lugar de decir "La razón por la que se hizo esto es porque cada Foo debe tener un Bar", simplemente diga "Cada Foo debe tener un Bar". Haga el comentario en una declaración activa de la razón, en lugar de una pasiva. En general, es un mejor estilo de escritura en general, se ajusta mejor a la naturaleza del código (que hace algo) y la frase the reason this was done no agrega información alguna. También evita exactamente el problema que está encontrando.

    
respondido por el Bobson 15.03.2013 - 19:51
23

Prefiero ninguno de los dos y, de hecho, dejaría de lado esa frase introductoria por completo y simplemente llegaría al punto. También trato de evitar solo decir "esto" porque no hay forma de saber si el comentario está sincronizado con el código. En otras palabras, en lugar de:

// The reason this was done is to prevent null pointer exceptions later on.

Yo diría:

// Frobnicate the widget first so foo can never be null.

El hecho de que esté agregando un comentario en absoluto implica que está declarando una razón, por lo que no necesita decirle a la gente de manera redundante que está explicando la razón. Simplemente haga la razón lo más específica posible, para que sepan lo más claramente posible cómo mantener ese código más adelante.

    
respondido por el Karl Bielefeldt 15.03.2013 - 19:54
4

En C # (y en la mayoría de las herramientas de documentación en otros idiomas) hay una diferencia entre la documentación y los comentarios en línea. Mi opinión personal es que siempre debe usar comentarios formales de estilo declarativo como Bobson y otros sugieren en la documentación de una clase o miembro, pero dentro del código, no hay nada de malo en ser menos formal. De hecho, a veces un comentario informal es más efectivo para explicar por qué se está haciendo algo que una exposición completa en inglés formal.

Aquí hay una muestra que creo que ilustra el punto.

/// <summary>
/// Takes data from the remote client and stores it in the database.
/// </summary>
/// <param name="data">The data to store.</param>
public void StoreData(ComplexObject data)
{
    // Don't take candy from strangers
    ComplexObject safeData = SanitizeData(data);
    ...
}
    
respondido por el p.s.w.g 15.03.2013 - 20:52
2

Otra idea a considerar sería una prueba unitaria bien diseñada que demuestra por qué el código funciona de la manera en que lo hace en lugar de escribir un comentario descriptivo. Esto tiene un par de beneficios sobre la escritura de comentarios:

  1. Los comentarios no siempre cambian cuando se cambia el código, lo que puede generar confusión más adelante.

  2. Las pruebas de unidades le dan al mantenedor una forma fácil de jugar con el código. Aprender una nueva base de código puede ser mucho más fácil si tiene unidades individuales que puede romper para observar qué cambios.

Aunque esta vía requiere más trabajo por adelantado, las pruebas unitarias pueden ser una excelente forma de documentación.

    
respondido por el mortalapeman 15.03.2013 - 20:22
1

Los buenos comentarios son difíciles de escribir, e incluso los mejores comentarios a menudo son difíciles de leer y comprender. Si su comentario es lo suficientemente conciso como para que lo absorba y lo suficientemente preciso para transmitir lo que necesito saber sobre el código, no me hace ninguna diferencia los pronombres que use.

No me gustaría disuadir a alguien de comentar su código porque está preocupado por el caso, el tiempo y la persona de sus pronombres.

    
respondido por el John M Gant 15.03.2013 - 20:14
1
  

La razón por la que uso "nosotros" en lugar de "yo" es porque escribo muchos textos académicos donde a menudo se prefiere "nosotros".

Es un estilo malo, incluso para trabajos académicos, a menos que esté tratando de ocultar quién realmente decidió ese punto exacto.

En cuanto a su pregunta específica: no dejaría ese comentario, a menos que comience con:

// TODO: clean this up, ...

o a menos que explique algo muy importante, eso podría no ser tan claro en el código. En ese caso, haga el comentario lo más breve posible.

    
respondido por el BЈовић 15.03.2013 - 21:05

Lea otras preguntas en las etiquetas