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

41

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?

Use "Nosotros": La razón por la que estamos haciendo esto es ...
Use "I": la razón por la que estoy haciendo esto es ...
Usa mi nombre: La razón por la que [my name]hice esto es ...
Voz pasiva: la razón por la que se hizo esto es ...
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.

documentation

— Alan Turing
fuente

Creo que todo depende de las preferencias personales. No veo ninguna razón por la cual una sea más clara que la otra en general.

— ConditionRacer

66

¿Qué tal # 5: "Cuando en el curso de los eventos humanos ...";)

— Waxwing

8

"Hace cuatro segundos y siete segundos nuestros antepasados aprendieron que el foo debe ser excluido para que nuestras fuerzas sean vencidas con NULL"

— Philip

Fuertemente relacionado con el inglés. SE: ¿Por qué los programadores siempre usan 'nosotros' cuando realmente quieren decir 'yo' o 'usted'? (Que, lamentablemente, estaba cerrado)

— Izkata

2

¿Por qué no lo dices This code was written like this because...? (Voz pasiva)

— Alvin Wong

77

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.

— Bobson
fuente

¿te importaría elaborar un poco sobre por qué harías eso? Sin una explicación, esta respuesta se parece más a una opinión simple, algo conflictiva con las pautas de respaldo : '... La opinión no es del todo mala, siempre y cuando esté respaldada con algo más que "porque soy un experto" , o "porque lo dije", o "solo porque". Use sus experiencias específicas para respaldar sus opiniones, como se indicó anteriormente, o señale alguna investigación que haya realizado en la web o en otro lugar que proporcione evidencia para respaldar sus afirmaciones ... '

— mosquito

15

@gnat "La razón por la que esto se hizo" no agrega nada a la explicación. Los comentarios deben contener solo el texto suficiente para transmitir el punto y nada más. Deje las sutilezas, preámbulos y otro texto de relleno.

— David Harkness

@gnat: en realidad, acababa de agregar más cuando vi tu comentario.

— Bobson

1

Creo que mi ejemplo fue demasiado simplista, porque de hecho "la razón por la que se hizo esto" no agrega nada. Pero hay casos en los que una situación difícil requiere alguna explicación, y en ese caso, me parece más natural usar "nosotros" o "yo", tal como usé "yo" varias veces en este comentario. Pero creo que su respuesta es clara en espíritu: "declarativo" sugiere: use la menor cantidad de palabras que entiendan claramente.

— Alan Turing

77

Leo //como becauseen la mayoría de los casos.

— Ilmo Euro

23

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.

— Karl Bielefeldt
fuente

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

— pswg
fuente

44

Nota al margen: SanitizeDatadebe devolver a SafeComplexObject. ;)

— Jon Purdy

Estoy de acuerdo, pero prefiero los comentarios literales (en lugar de los metafóricos), especialmente si puede haber desarrolladores de diferentes idiomas.

— John B. Lambe

2

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:

Los comentarios no siempre cambian cuando se cambia el código, lo que puede generar confusión más adelante.
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.

— mortalapeman
fuente

1

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.

— John M Gant
fuente

Permítanme aclarar: para los comentarios que se convertirán en parte de la documentación formal, es apropiado un tono más formal, y es mejor evitar "yo" y "nosotros". Lo que tenía en mente con esta respuesta era el comentario explicativo ocasional, por ejemplo, cuando has hecho algo que le parecerá mal al siguiente. En esos casos, donde solo las personas que trabajan en la misma base de código lo verán, digo que hagas lo que sea que transmita tu significado más claramente, incluso si es I wrote the code this way because...o what we really need here is.... En esos casos, un comentario claro es más importante que un estilo estricto.

— John M Gant

1

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.

— BЈовић
fuente