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

A veces me encuentro en situaciones en las que la parte del código que estoy escribiendo es (o parece ser ) tan evidente que su nombre se repetirá básicamente como un comentario:

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

(Ejemplo de C #, pero consulte la pregunta como independiente del idioma).

Un comentario como ese es inútil; ¿Qué estoy haciendo mal? ¿Es la elección del nombre lo que está mal? ¿Cómo podría comentar mejor partes como esta? ¿Debería omitir el comentario para cosas como esta?

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

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

Especialmente dado el uso de comentarios de Visual Studio que acompaña 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úe codificando, cuando no pueda recordar si UpdateLocationfue la ubicación donde 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 detalles en un campo, actualice los comentarios con esa información:

¿Qué tipo de actualización se debe Example.UpdateLocationusar 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 ser resueltos de forma iterativa. El propósito de los comentarios es ayudarlo a comprender el código cuando lo revisa seis meses después y no recuerda nada sobre cómo funciona el programa.

Y al igual que la programación, sus comentarios tienen que comenzar en alguna parte. Los comentarios tautológicos son los Hello World!comentarios, a medida que practique escribir y actualizar la documentación, su documentación inicial se volverá cada vez más resistente.

Los comentarios nunca deben duplicar su código. Los comentarios no deben responder la pregunta " ¿cómo? ", Sino solo " ¿por qué? " Y " ¿qué? ". Por qué se elige dicho algoritmo, 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 literaria para inspirarse.

Los comentarios deben describir el código, no duplicarlo. Este comentario de encabezado solo se duplica. Déjalo afuera.

¡Déjalos fuera!

Normalmente, es una buena práctica eliminar comentarios donde la información expresada en ellos ya está presente en otra parte. Si puede expresar el propósito de un método de forma clara e inequívoca dándole un buen nombre, entonces no hay necesidad de un comentario .

¡Ponerlos en!

Su ejemplo ilustra dos excepciones a esta regla:

Primero, "UpdateLocation" puede (según el contexto) ser ambiguo. En ese caso, debe darle un nombre mejor o proporcionar un comentario para eliminar la ambigüedad. Mejorar el nombre generalmente es la mejor opción, pero esto no siempre es posible (cuando implementa una API publicada, por ejemplo).

En segundo lugar, el "///" en C # indica un comentario que se 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, existen argumentos para insertar estos comentarios incluso si los métodos que documentan ya tienen nombres descriptivos. Incluso entonces, 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 para quienes está destinada 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 fácilmente el error.

En su ejemplo, es una propiedad, por lo que los métodos "get / set" 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.

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

Por lo tanto, si se trata de una API pública, siempre debe incluir al menos un <summary>comentario, incluso si el propósito de la función debe ser evidente para los lectores.

Sin embargo, esta es la excepción a la regla; en general, solo recuerda SECAR (no te repitas) .

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

_{Para mí, el caso de un beneficio claro fue cuando había una verificación automática de comentarios faltantes y estaba usando esa verificación para detectar el código donde se necesitaba completar información importante; 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 manera de evitar la duplicación flagrante . A lo largo de los años, he llegado a usar un par de "rellenos de plantillas" para casos como el suyo, principalmente como el nombre descriptivo y ver arriba .

Para este ejemplo en particular, usaría algo de "tipo autodescriptivo" (suponiendo que no sea el caso en el que la eliminación haría el trabajo), así:

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

_{Un ejemplo en el que podría usar ver los rellenos amables anteriores serían los comentarios Javadoc que requieren campos dedicados para el valor de retorno, parámetros y excepciones. Con bastante frecuencia, encuentro que tiene más sentido describir la mayoría o incluso todo esto en una oración de resumen única, 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 formalmente obligatorios con ver simplemente arriba , señalando al lector a la descripción resumida.}

Aquí hay una pregunta que me gustaría hacerme al pensar si agregar un comentario en una sección de código: ¿Qué puedo transmitir que ayude a la siguiente persona a comprender mejor la intención general del código, para que pueda actualizar, corregir o extenderlo más rápido y de manera más 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 ha escrito un código autodocumentado sólido, 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 desacelerar la caída de la sincronización con el código real con el tiempo y, por lo tanto, es 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, por usted, ya no serán aparentes en el código. Esto es casi inevitable porque un buen programador siempre programa para el futuro, es decir, no solo para hacer que el programa funcione una vez, sino para hacer todas sus correcciones y versiones y extensiones y modificaciones y puertos futuros y quién sabe qué hacer. También funciona correctamente. Ese último conjunto de objetivos es mucho más difícil y requiere mucha más reflexión para hacerlo bien. También es muy difícil expresarse bien en la mayoría de los lenguajes de computadora, que están más enfocados en la funcionalidad, es decir, en decir qué hace esto versión del programa debe hacer, ahora mismo, para 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á suficiente complejidad como para que alguien que la vea por primera vez no reconozca de inmediato de qué se trata. Esa es una oportunidad para un buen comentario, porque puede agregar algo sobre la intención de su código que un lector posterior probablemente apreciará de inmediato como útil para descifrar los detalles.

Por el contrario, en idiomas como el lenguaje Prolog basado en la lógica, expresar la búsqueda de una pequeña lista puede ser tan increíblemente trivial y sucinto que cualquier comentario que pueda agregar sería solo ruido. Por lo tanto, un buen comentario depende necesariamente del contexto. Eso incluye factores como las fortalezas del lenguaje 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 acerca de cómo debe entenderse y modificarse el programa en el futuro. [1]

Para aquellas partes de su código que realmente se documentan por sí mismas, los comentarios solo agregan ruido y aumentan el problema de coherencia para futuras versiones. Entonces no los agregue allí.

Pero para aquellas partes de su código donde 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 un comentario. Un buen comentario en tal caso es uno que le permite a algún futuro programador saber qué debe mantenerse igual, ese es el concepto de una afirmación invariable, por cierto, y qué está bien cambiar.

[1] Esto va más allá del tema de los comentarios, pero vale la pena mencionarlo: si descubres que tienes una idea muy clara de cómo podría cambiar tu código en el futuro, probablemente deberías pensar más allá de solo hacer un comentario e incrustar esos parámetros dentro del código en sí mismo, 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 futura persona desconocida en la dirección correcta. Al mismo tiempo, también desea evitar la generalización excesiva, ya que los humanos son notoriamente malos para predecir el futuro, y eso incluye el futuro de los cambios del programa. Por lo tanto, trate de definir y capturar dimensiones razonables y probadas del futuro en todos los niveles del diseño del programa, pero no lo haga.

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

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

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

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

Pienso 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 sola "oración"). Normalmente 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 entiende la idea).

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

Los comentarios deben usarse para hacer uno de los siguientes.

1. Información para los generadores de documentos para tomar. 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 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 informando al usuario que si cambian este número, también necesitan cambiar otro es extremadamente útil.
3. Escriba notas para explicar por qué un código de aspecto particularmente extraño es como es. Si tuvo que pensar en cómo hacer que un código funcione de una manera particular, y la solución no es evidente desde el principio, probablemente valga la pena explicar qué estaba tratando de hacer.
4. Etiquetado de entradas / salidas, si no están claras. Siempre es bueno saber cuáles se espera que sean 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 el código heredado de sierra como esto: page=0; // Sets the page to 0. Creo que cualquier persona competente podría resolver eso.

Quitaría la tautología pero mantendría el comentario, comentaría propiedades y nombres de 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 pasa allí, y por el comentario, tengo una idea clara de cómo usarlo.

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

Si se van a usar para generar documentación para que el equipo la construya (o si son solo comentarios en línea para explicar las cosas), entonces creo que es aceptable dejar eso de lado. Se puede suponer con seguridad que se explica por sí mismo; y cuando no es así, hay otros miembros del equipo cercanos que pueden explicarlo. Por supuesto, si resulta que no es evidente para muchas personas, debe agregarlo.

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

Creo que este tema se ha discutido ampliamente bajo nombres como "comentarios: antipatrones" o "¿son los comentarios un olor a código?" ( un ejemplo )

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

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

Si puedes escribir código que no requiera comentarios, ¡entonces has logrado programar el nirvana !.

¡Cuantos menos comentarios requiera su código , 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 UpdateLocationhace. ¿Es "actualizar" aquí un verbo o un adjunto sustantivo? 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 UpdateLocationaparentemente es una propiedad, pero el punto más importante es que a veces no hace daño declarar explícitamente algo que parece obvio.

Dejando a un lado la documentación compilada automáticamente, el código debe documentarse a sí mismo, por lo que los comentarios solo deben documentar donde el código no es suficiente para documentarse.

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