¿Cómo lidiar con la tautología en los comentarios? [cerrado]

En la mayoría de los proyectos en los que trabajo, no hay una cantidad significativa de tiempo para escribir comentarios detallados en cada miembro de la clase.

Eso no significa que no haya tiempo para comentarios; por el contrario, hay un montón de tiempo para comentarios tautológicos que devuelven una versión reformulada de lo que se está comentando. Funcionan muy bien como punto de partida .

Especialmente dado el uso de Visual Studio de los comentarios que acompañan a IntelliSense , es una buena idea comenzar con un poco de información sobre el campo:

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Y luego a medida que continúas codificando, cuando no puedes recordar si UpdateLocation fue la ubicación en la que se realizó la actualización, o la ubicación a la que se está enviando la actualización. Tendré que volver a visitar el código. Es en este punto que debe agregar esa información adicional:

class Example
{
    /// <summary>
    /// The Uri location where the update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Si alguna vez otro programador le pregunta sobre los detalles de un campo, actualice los comentarios con esa información:

  

¿Qué tipo de actualización debe usarse Example.UpdateLocation para almacenar?

class Example
{
    /// <summary>
    /// The Uri location where the Foo update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Al igual que un programa tiene errores, los buenos comentarios tienen errores que deben resolverse de manera iterativa. El propósito de los comentarios es ayudar a comprender el código cuando lo revisas seis meses después y no puedo recordar nada sobre cómo funciona el programa.

Y al igual que la programación, tus comentarios deben comenzar en algún lugar. Los comentarios tautológicos son el Hello World! de comentarios, a medida que practica la redacción y actualización de la documentación, su documentación de inicio será cada vez más resistente.

Los comentarios deben nunca duplicar su código. Los comentarios no deben responder a la pregunta " cómo? ", sino solo a " ¿por qué? " y " ¿qué? ". Por qué se elige un algoritmo de este tipo, cuáles son los supuestos implícitos aquí (a menos que su lenguaje sea lo suficientemente poderoso como para expresarlo con un sistema de tipos, contratos y similares), cuál es la razón para hacer esto, etc.

Recomiendo echar un vistazo a la práctica de Programación Literada para una inspiración.

Los comentarios deben describir el código, no duplicarlo. Este comentario de cabecera simplemente se duplica. Déjalo fuera.

¡Déjalos fuera!

Normalmente, es una buena práctica eliminar comentarios donde la información expresada en ellos ya está presente en otros lugares. Si puede expresar el propósito de un método de manera clara e inequívoca al darle un buen nombre, entonces existe no es necesario un comentario .

¡Ponlos en!

Su ejemplo ilustra dos excepciones a esta regla:

Primero, "UpdateLocation" puede (dependiendo del contexto) ser ambiguo. En ese caso, debe darle un nombre mejor o hacer un comentario para eliminar la ambigüedad. Por lo general, mejorar el nombre es la mejor opción, pero esto no siempre es posible (por ejemplo, cuando implementa una API publicada).

En segundo lugar, el "///" en C # indica un comentario que se pretende utilizar para generar automáticamente la documentación. El IDE utiliza estos comentarios para obtener información sobre herramientas, y existen herramientas (Sandcastle) que pueden generar archivos de ayuda, etc., a partir de estos comentarios. Como tal, hay argumentos para insertar estos comentarios, incluso si los métodos que documentan ya tienen nombres descriptivos. Aun así, sin embargo, muchos desarrolladores experimentados fruncirían el ceño ante la duplicación de información. El factor decisivo debe ser las necesidades de aquellos a quienes se destina la documentación.

Estoy totalmente en desacuerdo con las respuestas de "no escribir comentarios". ¿Por qué? Permítanme señalar cambiando un poco su ejemplo.

public Uri UpdateLocation ();

Entonces, ¿qué hace esta función:

• ¿Devuelve la "ubicación de actualización"? o
• ¿"Actualiza" la ubicación y devuelve la nueva ubicación?

Puedes ver que sin un comentario hay ambigüedad. Un recién llegado puede cometer el error fácilmente.

En su ejemplo, es una propiedad, por lo que los métodos "obtener / configurar" revelan que la segunda opción es incorrecta y de hecho significa "actualizar ubicación" y no "actualizar la ubicación". Pero es demasiado fácil cometer este error, especialmente en casos de palabras ambiguas como "actualizar". Juega seguro. No confunda a alguien nuevo en esto solo por ahorrar unos segundos de su tiempo.

Los bloques /// <summary> se utilizan para generar documentación para IntelliSense y la documentación de la API . / p>

Por lo tanto, si esta es una API pública, debería siempre incluir al menos un comentario <summary> , incluso si el propósito de la función debería ser self -vidente a los lectores.

Sin embargo, esta es la excepción a la regla; en general, solo recuerde DRY (No se repita) .

Rellene comentarios así solo si sabe cómo se beneficiaría de cosas como esa; de lo contrario, simplemente límpielos.

_{Para mí, el caso de beneficio claro fue cuando hubo una verificación automática de los comentarios faltantes y estaba usando esa verificación para detectar el código donde se necesitaba información importante para ser llenado para esto, de hecho, estaba llenando algunos marcadores de posición , solo para asegurarme de que el informe de la herramienta no contenga "falsas alarmas".}

Creo que siempre hay una forma de evitar la duplicación flagrante . A lo largo de los años he llegado a usar un par de "rellenos de plantilla" para casos como el suyo, principalmente como nombre auto-descriptivo y ver más arriba .

Para este ejemplo en particular, usaría algo de "tipo auto-descriptivo" (asumiendo que no es el caso en el que la eliminación haría el trabajo), por el estilo:

class Example
{
    /// <summary>
    /// Self descriptive method name.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

_{Un ejemplo cuando podría usar ver arriba rellenos de tipo sería Javadoc comentarios que requieren campos dedicados para valor de retorno, parámetros y excepciones. Con bastante frecuencia, me parece que tiene más sentido describir la mayoría o incluso todos estos en una sola oración de resumen, el método que devuelve < describe lo que se devuelve > para los parámetros proporcionados < describe los parámetros > . En casos como ese, relleno los campos requeridos formalmente con un simple ver arriba , apuntando al lector a la descripción resumida.}

Aquí hay una pregunta que me gusta preguntarme al pensar si agregar un comentario en una sección del código: ¿Qué puedo transmitir que ayudaría a la siguiente persona a comprender mejor la intención del código? , ¿para que puedan actualizarlo, arreglarlo o extenderlo de manera más rápida y confiable?

A veces, la respuesta correcta a esta pregunta es que no hay mucho que pueda agregar en ese punto del código, porque ya ha seleccionado nombres y convenciones que hacen que la intención sea lo más obvia posible. Eso significa que usted ha escrito un código sólido de autodocumentación, y que insertar un comentario allí probablemente restaría más de lo que ayudaría. (Tenga en cuenta que los comentarios redundantes en realidad pueden dañar la confiabilidad del código con el tiempo al disminuir la pérdida de sincronización con el código real con el tiempo y, por lo tanto, hacer que sea más difícil descifrar la intención real.

Sin embargo, en casi cualquier programa y en cualquier lenguaje de programación, encontrará puntos en los que ciertos conceptos críticos y decisiones tomadas por el programador original ya no serán evidentes en el código. Esto es bastante inevitable porque un buen programador siempre programa para el futuro, es decir, no solo para hacer que el programa funcione una sola vez, sino para hacer que todos sus muchos arreglos, versiones, extensiones y modificaciones en el futuro y los puertos y quién sabe qué también funciona correctamente. Este último conjunto de objetivos es mucho más difícil y requiere mucho más pensamiento para hacerlo bien. También es muy difícil expresarse bien en la mayoría de los lenguajes informáticos, que están más centrados en la funcionalidad, es decir, en lo que debe hacer esta versión del programa, ahora mismo, para poder que sea satisfactorio.

Aquí hay un ejemplo simple de lo que quiero decir. En la mayoría de los idiomas, una búsqueda rápida en línea de una pequeña estructura de datos tendrá la complejidad suficiente como para que alguien que la busque por primera vez no reconozca de inmediato lo que es. Esa es una oportunidad para un buen comentario, porque puede agregar algo sobre el intento de su código que un lector posterior probablemente apreciará de inmediato como útil para descifrar los detalles.

A la inversa, en lenguajes como el Prólogo basado en la lógica, expresar la búsqueda de una pequeña lista puede ser tan trivial y sucinto que cualquier comentario cualquier que pueda agregar sería solo ruido. Entonces, un buen comentario es necesariamente dependiente del contexto. Esto incluye factores tales como las fortalezas del idioma que está utilizando y el contexto general del programa.

La conclusión es esta: piensa en el futuro. Pregúntese qué es importante y obvio para usted sobre cómo se debe entender y modificar el programa en el futuro. [1]

Para aquellas partes de su código que son realmente auto documentadas, los comentarios solo agregan ruido y aumentan el problema de coherencia para futuras versiones. Así que no los agregues allí.

Pero para aquellas partes de su código en las que tomó una decisión crítica de varias opciones, o donde el código en sí es lo suficientemente complejo como para que su propósito sea oscuro, agregue su conocimiento especial en forma de comentario. Un buen comentario en tal caso es uno que le permite a un programador futuro saber qué debe mantenerse igual, ese es el concepto de una afirmación invariable, incidentalmente, y qué está bien cambiar.

[1] Esto va más allá del tema de los comentarios, pero vale la pena comentarlo: si descubre que tiene una idea muy clara de cómo podría cambiar su código en el futuro, probablemente debería pensar más allá de solo hacer un comentario y incruste esos parámetros en el propio código, ya que casi siempre será una forma más confiable de garantizar la confiabilidad de futuras versiones de su código que tratar de usar comentarios para dirigir a una persona desconocida en el futuro en la dirección correcta. Al mismo tiempo, también desea evitar el exceso de generalización, ya que los humanos son notoriamente malos para predecir el futuro, y eso incluye el futuro de los cambios en los programas. Por lo tanto, intente definir y capturar dimensiones de futuro razonables y bien probadas en todos los niveles de diseño del programa, pero no permita que lo distraiga en un ejercicio de generalización excesiva que es poco probable que se pague en el largo plazo. p>     

En mi propio código, con frecuencia dejaré en su lugar las tautologías de comentarios, incluidas las especialmente importantes como:

<?php
// return the result
return $result;
?>

... que obviamente contribuye poco en términos de hacer que el código sea más comprensible desde una perspectiva explicativa.

En mi opinión, estos comentarios aún tienen valor, si ayudan a mantener la consistencia visual de los patrones de color en el resaltador de sintaxis .

Creo que el código tiene una estructura que es muy similar al idioma inglés, en el sentido de que hay "oraciones" y "párrafos" (aunque un "párrafo" puede consistir completamente en una "oración"). Por lo general, incluyo un salto de línea y un resumen de una línea sobre cada "párrafo". Por ejemplo:

<?php
//get the id of the thing
$id = $_POST['id'];

//query the things out of the the database
$things = array();
$result = mysql_query("SELECT * FROM Things WHERE 'id' = $id");
while ($row = mysql_fetch_assoc($result)) {
    //create a proper Thing object or whatever
    $things[] = new Thing($row);
}

//return the things
return $things;
?>

(Ignore el código incompleto, las inyecciones de SQL, etc. Se le ocurre la idea).

Para mí, el comentario final genuinamente agrega valor al código, simplemente porque ayuda a delinear visualmente un "párrafo" de otro manteniendo un esquema de coloreado consistente.

Los comentarios deben usarse para realizar una de las siguientes acciones.

1. Información para los generadores de documentos para agarrar. Esto no puede ser subestimado, esto es extremadamente importante.
2. Advertencias sobre por qué un fragmento de código es como es y qué otras consideraciones. He tratado con el código escrito en 2 lenguajes de programación. Una parte clave de esto era tener una estructura común entre los dos idiomas. Un comentario en ambas ubicaciones para informar al usuario de que si cambian este número, también necesitan cambiar otro es extremadamente útil.
3. Escriba notas para explicar por qué un trozo de código particularmente extraño es así. Si tuvo que pensar en cómo hacer que una pieza de código funcione de una manera particular y la solución no es evidente desde el principio, probablemente valga la pena explicar qué intentaba hacer.
4. Etiquetado de entradas / salidas, si no están claras. Siempre es bueno saber cuáles serán sus entradas y en qué formato están.

Los comentarios no deben usarse para hacer lo siguiente:

1. Explica cosas que son extremadamente obvias. Una vez vi un código heredado como este: page=0; // Sets the page to 0 . Creo que cualquier persona competente podría darse cuenta de eso.

Eliminaré la tautología pero mantendré el comentario, comentaré las propiedades y los nombres de las variables dando un valor de muestra, para que el uso se entienda claramente:

property UpdateLocation:TUpdateLocation;  // url="http://x/y/3.2/upd.aspx",proto=http

Ahora sé exactamente lo que ocurre allí y, a partir del comentario, tengo una idea clara de cómo usarlo.

Yo diría que depende del propósito de los comentarios.

Si se van a utilizar para generar documentación para que la compile el equipo (o si solo son comentarios en línea para explicar las cosas), creo que es aceptable dejar eso de lado. Se puede suponer con seguridad que es autoexplicativo; y cuando no lo es, hay otros miembros del equipo cercanos que pueden explicarlo. Por supuesto, si resulta que no es evidente para mucha gente, debes agregarlo.

Si los comentarios generarán documentación para algún equipo geográficamente distante, entonces pondré toda la documentación allí.

Creo que este tema ha sido discutido bastante extensamente bajo nombres como "comentarios: anti-patrones", o "¿son los comentarios un olor de código?" ( un ejemplo ).

Tiendo a estar de acuerdo con la idea general de que los comentarios deben agregar nueva información, no duplicar. Al agregar comentarios triviales como esos, estás violando el DRY y disminuyendo la relación señal / ruido del código. Tiendo a encontrar comentarios de alto nivel que explican las responsabilidades, las razones detrás y el uso de ejemplos de la clase mucho más útil que los comentarios por propiedad (especialmente los superfluos).

Personalmente, en su ejemplo, dejaría un comentario (si realmente no hay nada útil que agregar sobre la propiedad).

Si puede escribir código que no requiera comentarios, habrá logrado programar nirvana.

¡Cuantos menos comentarios su código requiera , mejor será el código!

  

Un comentario como ese es inútil; ¿Qué estoy haciendo mal?

Solo parece inútil si ya sabes lo que hace UpdateLocation . ¿Es "actualizar" aquí un verbo o un sustantivo adjunto? Es decir, ¿es esto algo que actualiza la ubicación o es la ubicación de la actualización? Uno podría inferir lo último del hecho de que UpdateLocation es aparentemente una propiedad, pero el punto más importante es que a veces no hace daño declarar explícitamente algo que parece obvio.

Dejando de lado la documentación compilada automáticamente, el código debe documentarse, de modo que los comentarios solo deben documentar donde el código no es suficiente para documentarse.

"Ubicación" es algo obvio, pero "Actualizar" podría ser un poco vago. Si no puedes escribir un nombre mejor, ¿puedes ofrecer más detalles en el comentario? ¿Actualización de qué? ¿Porqué necesitamos esto? ¿Cuáles son algunas suposiciones (es nulo permisible)?