Quiero saber de usted cualquier consejo y experiencia de escribir comentarios en su código. ¿Cómo los escribes de la manera más fácil e informativa? ¿Qué hábitos tienes al comentar partes del código? Tal vez algunas recomendaciones exóticas?

Espero que esta pregunta recopile los consejos y recomendaciones más interesantes para comentar, algo útil de lo que todos puedan aprender.

OK, comenzaré

1. Por lo general, no uso /* */comentarios incluso cuando necesito comentar muchas líneas.

   Ventajas : el código se ve mejor visualmente que cuando se mezcla dicha sintaxis con comentarios de una línea. La mayoría de los IDE tienen la capacidad de comentar el texto seleccionado y generalmente lo hacen con una sintaxis de una línea.

   Desventajas : Difícil editar dicho código sin IDE.

2. Coloque "punto" al final de cualquier comentario terminado.

   Por ejemplo:

   //Recognize wallpaper style. Here I wanted to add additional details
   int style = int.Parse(styleValue);
   //Apply style to image.
   Apply(style);
   

   Ventajas : Coloque "punto" solo en los comentarios que haya terminado. A veces puede escribir información temporal, por lo que la falta de "punto" le indicará que desea regresar y agregará texto adicional a este comentario.

3. Alinee el texto en las enumeraciones, parámetros de comentarios, etc.

   Por ejemplo:

   public enum WallpaperStyle
   {
       Fill = 100,     //WallpaperStyle = "10"; TileWallpaper = "0".
       SizeToFit = 60, //WallpaperStyle = "6";  TileWallpaper = "0".
       Stretch = 20,   //WallpaperStyle = "2";  TileWallpaper = "0".
       Tile = 1,       //WallpaperStyle = "0";  TileWallpaper = "1".
       Center = 0      //WallpaperStyle = "0";  TileWallpaper = "0".
   };
   

   Ventajas : Simplemente se ve mejor y es visualmente más fácil de encontrar lo que necesita.

   Desventajas : pasar tiempo para alinearse y más difícil de editar.

4. Escriba un texto en el comentario que no pueda obtener analizando el código.

   Por ejemplo, comentario estúpido:

   //Apply style.
   Apply(style);
   

   Ventajas : tendrá un código claro y pequeño con solo información útil en los comentarios.

Algunas de las declaraciones a continuación son bastante personales, aunque con cierta justificación, y están destinadas a ser de esta manera.

Tipos de comentarios

Para la versión breve ... uso comentarios para:

• comentarios finales que explican los campos en las estructuras de datos (aparte de eso, realmente no uso comentarios de una sola línea)
• comentarios de varias líneas excepcionales u orientados a fines sobre bloques
• documentación pública de usuario y / o desarrollador generada desde la fuente

Lea a continuación los detalles y las razones (posiblemente oscuras).

Comentarios finales

Dependiendo del idioma, ya sea utilizando comentarios de una sola línea o comentarios de varias líneas. ¿Por qué depende? Es solo un problema de estandarización. Cuando escribo código C, prefiero el código ANSI C89 antiguo de forma predeterminada, por lo que prefiero tenerlo siempre /* comments */.

Por lo tanto, tendría esto en C la mayor parte del tiempo y, a veces (depende del estilo de la base de código) para lenguajes con una sintaxis tipo C:

typedef struct STRUCT_NAME {
  int fieldA;                /* aligned trailing comment */
  int fieldBWithLongerName;  /* aligned trailing comment */
} TYPE_NAME;

Emacs es agradable y hace eso por mí M-;.

Si el lenguaje admite comentarios de una sola línea y no está basado en C, estaré más obligado a usar los comentarios de una sola línea. De lo contrario, me temo que ahora he tomado el hábito. Lo cual no es necesariamente malo, ya que me obliga a ser conciso.

Comentarios multilínea

No estoy de acuerdo con tu precepto usando comentarios de una sola línea para que esto sea más atractivo visualmente. Yo uso esto:

/*
 * this is a multi-line comment, which needs to be used
 * for explanations, and preferably be OUTSIDE the a
 * function's or class' and provide information to developers
 * that would not belong to a generated API documentation.
 */

O esto (pero ya no lo hago tan a menudo, excepto en una base de código personal o principalmente para avisos de derechos de autor; esto es histórico para mí y proviene de mi formación académica. Desafortunadamente, la mayoría de los IDE lo arruinan cuando se usa el formateo automático) :

/*
** this is another multi-line comment, which needs to be used
** for explanations, and preferably be OUTSIDE the a
** function's or class' and provide information to developers
** that would not belong to a generated API documentation.
*/

Si fuera necesario, comentaría en línea usando lo que mencioné anteriormente para los comentarios finales, si tiene sentido usarlo en una posición final. En un caso de devolución muy especial, por ejemplo, o para documentar switchlas casedeclaraciones de un (raro, no uso switch a menudo), o cuando documente ramas en un if ... elseflujo de control. Si ese no es uno de estos, generalmente un bloque de comentarios fuera del alcance que describe los pasos de la función / método / bloque tiene más sentido para mí.

Los uso de manera excepcional, excepto si se codifica en un idioma sin soporte para comentarios de documentación (ver más abajo); en cuyo caso se vuelven más frecuentes. Pero en el caso general, realmente es solo para documentar cosas que están destinadas a otros desarrolladores y son comentarios internos que realmente deben destacarse. Por ejemplo, para documentar un bloque vacío obligatorio como un bloque "forzado" catch:

try {
  /* you'd have real code here, not this comment */
} catch (AwaitedException e) {
  /*
   * Nothing to do here. We default to a previously set value.
   */
}

Lo cual ya es feo para mí, pero lo toleraría en algunas circunstancias.

Comentarios de documentación

Javadoc y col.

Por lo general, los uso en métodos y clases para documentar versiones que introducen una característica (o la cambian), especialmente si es para una API pública, y para proporcionar algunos ejemplos (con casos claros de entrada y salida, y casos especiales). Aunque en algunos casos un caso unitario podría ser mejor para documentarlos, las pruebas unitarias no son necesariamente legibles por humanos (no importa qué cosa DSL use).

Me molestan un poco para documentar los campos / propiedades, ya que prefiero los comentarios finales para esto y no todo el marco de generación de documentación admite comentarios de documentación final. Doxygen sí, por ejemplo, pero JavaDoc no, lo que significa que necesita un comentario principal para todos sus campos. Sin embargo, puedo sobrevivir a eso, ya que las líneas Java son relativamente largas de todos modos la mayor parte del tiempo, por lo que un comentario final me asustaría igualmente al extender la línea más allá de mi umbral de tolerancia. Si Javadoc alguna vez considerara mejorar eso, estaría mucho más feliz.

Código comentado

Utilizo una sola línea solo por una razón, en lenguajes tipo C (excepto si compilo para C estricto, donde realmente no los uso): comentar cosas mientras codifico. La mayoría de los IDE tendrán que alternar para comentarios de una sola línea (alineados en sangría o en la columna 0), y eso se ajusta a ese caso de uso para mí. El uso de la alternancia para comentarios de varias líneas (o la selección en el medio de las líneas, para algunos IDE) hará que sea más difícil cambiar fácilmente entre comentarios / comentarios.

Pero como estoy en contra del código comentado en el SCM, eso suele ser muy breve porque eliminaré los fragmentos comentados antes de comprometerme. (Lea mi respuesta a esta pregunta sobre "comentarios en línea editados y SCM" )

Estilos de comentario

Normalmente tiendo a escribir:

• completar oraciones con la gramática correcta (incluida la puntuación) para comentarios de documentación, ya que se supone que deben leerse más adelante en un documento de API o incluso como parte de un manual generado.
• bien formateado pero más laxo en la puntuación / mayúsculas para bloques de comentarios de líneas múltiples
• bloques finales sin puntuación (debido al espacio y generalmente porque el comentario es breve, que se lee más como una declaración entre paréntesis)

Una nota sobre programación literaria

Es posible que desee interesarse en la programación literaria , como se presenta en este documento por Donald Knuth .

El paradigma de la programación alfabetizada representa [...] un alejamiento de escribir programas de la manera y el orden impuestos por la computadora, y en cambio permite a los programadores desarrollar programas en el orden exigido por la lógica y el flujo de sus pensamientos. 2 Los programas literarios se escriben como una exposición ininterrumpida de la lógica en un lenguaje humano ordinario, muy parecido al texto de un ensayo [...].

Las herramientas de programación alfabetizadas se utilizan para obtener dos representaciones de un archivo fuente alfabetizado: una adecuada para su posterior compilación o ejecución por una computadora, el código "enredado" y otra para ver como documentación formateada, que se dice que está "tejida" fuente alfabetizada.

Como nota al margen y ejemplo: el marco JavaScript underscore.js , a pesar del incumplimiento de mi estilo de comentario, es un buen ejemplo de una base de código bien documentada y una fuente anotada bien formada , aunque tal vez no sea la mejor para usar como una referencia de API).

Estas son convenciones personales . Sí, podría ser raro (y tú también podrías serlo). Está bien, siempre y cuando cumpla y cumpla con las convenciones de código de su equipo cuando trabaje con sus compañeros, o no ataque radicalmente sus preferencias y conviva agradablemente. Es parte de su estilo, y debe encontrar la línea fina entre desarrollar un estilo de codificación que lo defina como un codificador (o como seguidor de una escuela de pensamiento u organización con la que tiene una conexión) y respetar la convención de un grupo para mantener la coherencia. .

Cuando iba a la universidad siempre me enseñaron a comentar cada línea de código y cada encabezado de método. Fue tocado / adoctrinado hasta el punto de que lo hiciste sin dudarlo. Habiendo sido parte de varios equipos de desarrollo ágil en diferentes compañías, puedo decir que puedo escribir un comentario una vez en una luna azul.

La razón de esto es doble, en primer lugar, ya no deberíamos escribir largos métodos monolíticos que hagan 101 cosas diferentes, la clase, el método y los nombres de las variables deberían autodocumentarse. Tome el siguiente método de inicio de sesión como ejemplo.

public void Login(string username, string password)
{
    // Get the user entity
    var user = userRepository.GetUser(username);


    // Check that the user exists
    if (user == null)
    {
        throw new UserNotFoundException();
    }

    // Check that the users password matched
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }

    //Check that the users account has not expired
    if (user.Expired)
    {
        throw new UserExpiredException();
    }

    //Mark user as logged in
    ...
}

Esto puede repetirse con algo que es mucho más legible y quizás reutilizable:

public void Login(string username, string password)
{
    var user = GetUserForUsername(username);

    CheckUsersPasswordMatched(user, password);

    CheckUserAccountNotExpired(user);

    MarkUserAsLoggedIn(user);
}

private void User GetUserForUsername(string username)
{
    var user = userRepository.GetUser(username);

    if (user == null)
    {
        throw new UserNotFoundException();
    }
    return user;
}

private void CheckUsersPasswordMatched(User user, string password)
{
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }
}

private void CheckUserAccountNotExpired(User user)
{
    if (user.Expired)
    {
        throw new UserExpiredException();
    }
}

Puede ver claramente desde el método de inicio de sesión lo que está sucediendo. Puede ver esto como un trabajo extra, pero sus métodos son pequeños y solo tienen un trabajo. Además, los nombres de los métodos son descriptivos, por lo que no es necesario escribir ningún comentario en el encabezado del método. Si termina con demasiados métodos, esto es una indicación de que los métodos relacionados se deben refactorizar en otro objeto, como un Servicio de autenticación de usuario, recuerde que un objeto solo debe tener un trabajo.

En segundo lugar, cada código que escriba, incluidos los comentarios, debe mantenerse, cuantos más comentarios tenga, más debe mantener. Si cambia el nombre de una clase o una variable, obtendrá un error de compilación, pero si cambia la forma en que funciona una sección de código o la elimina y no actualiza ningún comentario relacionado, no habrá ningún error de compilación y los comentarios se quedarán dando vueltas causando confusión .

Si está escribiendo una API, entonces creo que las interfaces, clases y enumeraciones públicas deben tener comentarios de encabezado bien escritos para la documentación.

Concéntrese menos en el formato y más en el contenido. Por ejemplo, los comentarios en tu ejemplo no me dicen nada nuevo. Son peores que inútiles, ya que restan la lectura del código, y comentarios como estos son, en el mejor de los casos, una vaga referencia a lo que el programador original pensó que estaba haciendo en el momento en que lo escribió. Puedo ver en el ejemplo de código que estás aplicando un estilo "apply (Style)", puedo leer la fuente. No puedo leer tu mente, por qué lo haces es lo que el comentario debería decirme. por ejemplo, en lugar de

//Apply style.

Apply(style);

debiera ser

// Unlike the others, this image needs to be drawn in the user-requested style apply(style);

La mayoría de nosotros trabajamos en equipos con el código existente, formateamos de la misma manera que lo hace el resto del equipo, como ya se está haciendo. Consistencia de mucho más importante que bonita.

En la medida de lo posible, escriba su código de manera que los comentarios sean completamente extraños. Solo agregue comentarios cuando el código no se pueda escribir de tal manera que haga obvio un concepto importante.

Mi preferencia es mantenerlo realmente simple. Evito todo tipo de formato elegante. La razón principal de esto es que creo que el código fuente debería ser cómodamente editable incluso con el editor de texto más simple. Tampoco nunca envuelvo los párrafos de texto, sino que dejo que el editor realice un ajuste suave (sin agregar nuevas líneas).

A menudo veo comentarios como ese, y algunas herramientas lo generan automáticamente de esa manera:

/** 
 * This is an example, how to waste vertical space,
 * and how to use useless asterixes.
 */

Dos líneas menos:

/** This is an example, how to spare vertical space,
    and how to avoid useless asterixes. */

Los IDE y los editores, marginalmente por encima del nivel del bloc de notas, pueden detectar comentarios e imprimirlos en un color diferente. No es necesario decorar el comienzo de la línea con asteriscos.

Incluso ahorra algunos bytes, si usa una pestaña para sangrar.

Si no utiliza un editor sofisticado, que muestra el comentario en un tono gris, la gran cantidad de asteriscos funcionará como un énfasis y atraerá su atención, que es lo opuesto a lo correcto: quedarse atrás.

Aquí hay un "antipatrón" que he encontrado en todo el código de mi trabajo: el uso de comentarios como un "registro de cambios"; Para eso sirve el registro en su sistema de control de versiones. El código está lleno de cosas como:

// 05-24-2011 (John Doe): Changed this method to use Foo class instead of Bar

y generalmente incluye el código antiguo que se ha comentado (de nuevo, ese es el punto de un sistema VCS, por lo que no es necesario que esté en el código después de escribir el nuevo código). También hay que evitar comentarios repetidos como "¿Por qué necesitamos esto?" o peor aún, "Esto probablemente debería renombrarse" (porque hay herramientas sofisticadas para renombrar, por lo que en el tiempo que le tomó escribir ese comentario, podría haber cambiado el nombre de la cosa). Nuevamente, trato con ambos comentarios de forma regular, en la línea de:

// (John Doe) 05-24-2011 not sure why we are using this object?
FooBar oFooBar = Quux.GetFooBar(iFooBarID, bSomeBool);
oFooBar.DiscombobulateBaz();

// (John Doe). This method is poorly named, it's used for more 
// than just frazzling arvadents
public int FrazzleArvadent(int iArvadentID)

1. Elija un sistema de documentación como doxygen y quédese con él. Siga revisando los documentos producidos.
2. Trate de imaginar a alguien nuevo en la base de código entrando y leyendo sus documentos, ¿podrían comenzar a usarlo? Los pasantes son realmente buenos para eso, siéntese uno nuevo con su base de documentos existente y una tarea simple y vea cuán lejos llegan, si tropiezan, muy seguro de que cualquier cosa que les haya dicho para que vuelvan a funcionar va en los documentos.
3. Haga que los comentarios de documentación sean un punto de control en sus procesos de revisión.

Los lectores de códigos generalmente intentan responder tres preguntas:

1. ¿Qué hace esta clase o función? Si esto es difícil de responder, entonces hace demasiado. El código que es difícil de documentar suele ser simplemente incorrecto.
2. ¿Como lo uso? Un ejemplo puede ser lo suficientemente bueno.
3. Ese código es sorprendente. ¿Por qué hiciste eso? Respuestas más probables: evitar un error en componentes de terceros, porque la técnica obvia resultó ser demasiado lenta

Todo lo demás debe expresarse en el código. Al igual que escribir en prosa, este es un arte y requiere mucha práctica. La única forma de saber si su código es comprensible es hacer que alguien más lo lea. Cuando no entiendan algo, no lo expliquen verbalmente. Mejora el código. Agregue comentarios como último recurso.

Si veo "doble longitud", preguntaré "¿Cuál es la unidad de medida?" No añadas un comentario. Cambiar el nombre de la variable. Si veo un bloque de código y digo "¿qué hace esto?", No agregue un comentario. Extraer una función con un nombre significativo. Si no puede extraer una función porque necesitaría 17 argumentos, refactorice el código.