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

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

The reason we are doing this is...

La razón por la que uso "nosotros" en lugar de "yo" es porque hago mucha escritura académica donde a menudo se prefiere "nosotros".

Así que aquí está la pregunta. ¿Hay una buena razón para preferir uno sobre el otro al documentar el código?

1. Use "Nosotros": La razón por la que estamos haciendo esto es ...
2. Use "I": la razón por la que estoy haciendo esto es ...
3. Usa mi nombre: La razón por la que [my name]hice esto es ...
4. Voz pasiva: la razón por la que se hizo esto es ...
5. Tampoco: 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 eso solo agrega otra cosa que necesita ser cambiado al mantener el código.

Yo 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 adapta mejor a la naturaleza del código (que hace algo), y la the reason this was donefrase no agrega información alguna. También evita exactamente el problema que estás encontrando.

Prefiero ninguno de los dos, y en realidad dejaría de lado esa frase introductoria y simplemente iría al grano. También trato de evitar decir "esto" porque no deja 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 implica que está expresando una razón, por lo que no necesita decirle a las personas de manera redundante que está explicando la razón. Simplemente haga que la razón sea lo más específica posible, para que sepan con la mayor claridad posible cómo mantener ese código más adelante.

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 y 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);
    ...
}

Otra idea a considerar sería una prueba unitaria bien diseñada que demuestre 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 escribir 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.

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

Odiaría disuadir a alguien de comentar su código porque están preocupados por el caso, el tiempo y la persona de sus pronombres.

La razón por la que uso "nosotros" en lugar de "yo" es porque hago mucha escritura académica donde a menudo se prefiere "nosotros".

Es un mal estilo, incluso para trabajos académicos, a menos que esté tratando de ocultar quién decidió realmente 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 estar tan claro en el código. En ese caso, haga el comentario lo más breve posible.