documentation remarks ¿Qué es el código de auto-documentación y puede reemplazar el código bien documentado?




remarks c# (24)

El código en sí siempre será la explicación más actualizada de lo que hace su código, pero en mi opinión es muy difícil que explique la intención , que es el aspecto más importante de los comentarios. Si está escrito correctamente, ya sabemos lo que hace el código, ¡solo necesitamos saber por qué demonios lo hace!

Tengo un colega que insiste en que su código no necesita comentarios, es "auto-documentación".

He revisado su código, y aunque es más claro que el código que he visto producir a otros, todavía no estoy de acuerdo con que el código de auto-documentación sea tan completo y útil como el código comentado y documentado.

Ayúdame a entender su punto de vista.

  • ¿Qué es el código auto documentado?
  • ¿Puede realmente reemplazar código bien comentado y documentado?
  • ¿Hay situaciones donde es mejor que el código bien documentado y comentado?
  • ¿Hay ejemplos en los que el código no pueda autodocumentarse sin comentarios?

Tal vez solo sean mis propias limitaciones, pero no veo que pueda ser una buena práctica.

Esto no pretende ser un argumento; por favor, no mencione las razones por las que un código bien comentado y documentado es de alta prioridad. Hay muchos recursos que lo demuestran, pero no son convincentes para mi compañero. Creo que necesito entender más completamente su perspectiva para convencerlo de lo contrario. Si es necesario, comience una nueva pregunta, pero no discuta aquí.

Wow, respuesta rápida! Lea todas las respuestas existentes y proporcione comentarios a las respuestas en lugar de agregar nuevas respuestas, a menos que su respuesta sea realmente diferente a cualquier otra respuesta aquí.

Además, aquellos de ustedes que están discutiendo contra el código de auto-documentación, esto es principalmente para ayudarme a entender la perspectiva (es decir, los aspectos positivos) de los evangelistas del código de auto-documentación. Espero que los demás te rechacen si no te mantienes en el tema.


Cuando escribo código matemático, a veces me resulta útil escribir comentarios largos, como ensayos, explicando las matemáticas, las convenciones de notación que usa el código y cómo encaja todo. Estamos hablando de cientos de líneas de documentación, aquí.

Intento que mi código sea lo más auto documentado posible, pero cuando vuelvo a trabajar en él después de unos meses, realmente necesito leer la explicación para evitar hacer un hash.

Ahora, por supuesto, este tipo de medida extrema no es necesaria para la mayoría de los casos. Creo que la moraleja de la historia es: diferentes códigos requieren diferentes cantidades de documentación. Algunos códigos pueden escribirse con tanta claridad que no necesitan comentarios, así que escríbalos de manera clara y ¡no use comentarios allí!

Pero muchos códigos necesitan comentarios para tener sentido, así que escríbalos lo más claramente posible y luego use tantos comentarios como sea necesario ...


En primer lugar, es bueno saber que el código de su colega es, de hecho, más claro que el otro código que ha visto. Significa que probablemente no esté usando la "autodocumentación" como excusa para ser demasiado perezoso para comentar su código.

El código de auto-documentación es un código que no requiere comentarios de texto libre para que un lector informado entienda lo que está haciendo. Por ejemplo, esta pieza de código se auto-documenta:

print "Hello, World!"

y así es esto:

factorial n = product [1..n]

y así es esto:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

Ahora, esta idea de un "lector informado" es muy subjetiva y situacional. Si usted o alguien más está teniendo problemas para seguir el código de su colega, entonces haría bien en volver a evaluar su idea de un lector informado. Se debe asumir cierto nivel de familiaridad con el idioma y las bibliotecas que se utilizan para poder llamar el autodocumento de códigos.

El mejor argumento que he visto para escribir "código de autodocumentación" es que evita el problema de los comentarios de texto libre que no están de acuerdo con el código tal como está escrito. La mejor crítica es que si bien el código puede describir qué y cómo se está haciendo solo, no puede explicar por qué algo se está haciendo de una determinada manera.


Me sorprende que nadie haya producido la " Programación Literate ", una técnica desarrollada en 1981 por Donald E. Knuth de TeX y la fama "El arte de la programación por computadora".

La premisa es simple: dado que el compilador debe entender el código y los compiladores simplemente lo desecha, por qué no le da a todos lo que necesitan: una descripción textual completa de la intención del código, sin restricciones de los requisitos del lenguaje de programación. , para el lector humano y código puro para el compilador.

Las herramientas de Programación Literada hacen esto al darle un marcado especial para un documento que le dice a las herramientas qué parte debe ser fuente y qué es texto. Más tarde, el programa extrae las partes del código fuente del documento y ensambla un archivo de código.

Encontré un ejemplo en la web: http://moonflare.com/code/select/select.nw o la versión HTML http://moonflare.com/code/select/select.html

Si puede encontrar el libro de Knuth sobre él en una biblioteca (Donald E. Knuth, Literate Programming, Stanford, California: Centro para el estudio del lenguaje y la información, 1992, CSLI Lecture Notes, no. 27.) debe leerlo.

Eso es código autodocumentado, completo con razonamiento y todo. Incluso hace un buen documento, todo lo demás son comentarios bien escritos :-)


El problema real con el llamado código de autodocumentación es que transmite lo que realmente hace. Si bien algunos comentarios pueden ayudar a alguien a entender mejor el código (por ejemplo, pasos de algoritmos, etc.) es en cierto grado redundante y dudo que convenza a su compañero.

Sin embargo, lo que es realmente importante en la documentación es lo que no se ve directamente en el código: intención subyacente, suposiciones, impactos, limitaciones, etc.

Poder determinar que un código hace X de una mirada rápida es mucho más fácil que determinar que un código no hace Y. Él tiene que documentar Y ...

Podría mostrarle un ejemplo de un código que se ve bien, es obvio, pero en realidad no cubre todas las bases de la entrada, por ejemplo, y ver si lo encuentra.


Bueno, ya que se trata de comentarios y códigos, veamos algunos códigos reales. Compara este código típico:

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

A este código de auto-documentación, que muestra lo que se está haciendo:

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2)

Y luego a este código documentado, que explica mejor por qué se está haciendo:

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2)

Y la versión final del código como documentación con cero comentarios necesarios:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2)
    return displacement;
}

Aquí hay un ejemplo de un estilo de comentario pobre:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

En el último ejemplo, los comentarios se usan cuando las variables deberían haber sido nombradas descriptivamente en su lugar, y los resultados de una operación se resumen cuando podemos ver claramente qué es la operación. Preferiría el segundo ejemplo autodocumentado a este cualquier día, y quizás de eso es de lo que habla su amigo cuando dice un código autodocumentado.

Yo diría que depende del contexto de lo que está haciendo. Para mí, el código auto documentado es probablemente suficiente en este caso, pero también es útil un comentario que detalla la metodología detrás de lo que se hace detrás (en este ejemplo, la ecuación).


Todo va a estar en lo que el equipo valora en su documentación. Sugeriría que documentar por qué / intención en lugar de cuán importante es, y esto no siempre se refleja en el código de auto-documentación. obtener / establecer no son obvios, pero el cálculo, la recuperación, etc., es parte del por qué se debe expresar.

También tenga en cuenta la diferencia en su equipo si viene de diferentes nacionalidades. Las diferencias en la dicción pueden convertirse en nombres de métodos:

Búsqueda de Bisección

Búsqueda binaria

BinaryChop

Estos tres métodos aportados por desarrolladores entrenados en 3 continentes diferentes hacen lo mismo. Solo al leer los comentarios que describían el algoritmo pudimos identificar la duplicación en nuestra biblioteca.


el código de auto-documentación es una buena práctica y, si se hace correctamente, puede transmitir fácilmente el significado del código sin leer demasiados comentarios. especialmente en situaciones donde el dominio es bien comprendido por todos en el equipo.

Dicho esto, los comentarios pueden ser muy útiles para los recién llegados o para los evaluadores o para generar documentación / archivos de ayuda.

el código de auto-documentación + los comentarios necesarios contribuirán en gran medida a ayudar a las personas en todos los equipos.


El punto de vista de que el código se auto documenta me vuelve loco. Una línea particular de código o un algoritmo secundario puede, de hecho, autodocumentarse, pero su propósito en la imagen mayor simplemente no lo es.

Me frustré tanto con esto hace uno o dos meses que escribí una publicación completa en el blog que describía mi punto de vista. Publicar aquí .


El código de auto-documentación es un buen ejemplo de "DRY" (No se repita). No duplique la información en los comentarios que está, o puede estar, en el código mismo.

En lugar de explicar para qué se utiliza una variable, cambie el nombre de la variable.

En lugar de explicar lo que hace un breve fragmento de código, extráigalo en un método y asígnele un nombre descriptivo (tal vez una versión abreviada de su texto de comentario).

En lugar de explicar qué hace una prueba complicada, extraiga eso también en un método y asígnele un buen nombre.

Etc.

Después de esto, terminas con un código que no requiere tanta explicación, se explica a sí mismo, así que debes eliminar los comentarios que simplemente repiten la información en el código.

Esto no significa que no tenga ningún comentario, hay cierta información que no puede incluir en el código, como la información sobre la intención (el "por qué"). En el caso ideal, el código y los comentarios se complementan entre sí, cada uno de los cuales agrega un valor explicativo único sin duplicar la información en el otro.


Yo diría, como muchos de ustedes lo hacen, que para ser verdaderamente auto-documentado, el código debe mostrar algún tipo de intención. Pero me sorprende que nadie haya mencionado aún el BDD - Behavior Driven Development . Parte de la idea es que tiene pruebas automatizadas (código) que explican la intención de su código, lo cual es tan difícil de hacer obvio de lo contrario.

Good domain modeling 
+ good names (variabes, methods, classes) 
+ code examples (unit tests from use cases) 
= self documenting software 

La diferencia es entre "qué" y "cómo".

  • Debes documentar "qué" hace una rutina.
  • No debe documentar "cómo" lo hace, a menos que haya casos especiales (por ejemplo, consulte un documento de algoritmo específico). Eso debería ser auto documentado.

el código de auto-documentación normalmente usa nombres de variables que coinciden exactamente con lo que el código está haciendo para que sea fácil entender lo que está pasando

Sin embargo, tal "código de auto-documentación" nunca reemplazará los comentarios. A veces, el código es demasiado complejo y el código de autodocumentación no es suficiente, especialmente en lo que respecta al mantenimiento.

Una vez tuve un profesor que creía firmemente en esta teoría. De hecho, lo mejor que recuerdo de él es que "los comentarios son para mariquitas".
Al principio nos tomó a todos por sorpresa, pero tiene sentido.
Sin embargo, la situación es que aunque puede comprender lo que está sucediendo en el código, pero alguien con menos experiencia puede ir detrás de usted y no entender lo que está sucediendo. Esto es cuando los comentarios se vuelven importantes. Sé que muchas veces no creemos que sean importantes, pero hay muy pocos casos en los que los comentarios son innecesarios.


Mi opinión está escrita en este post:

El único consejo para documentar su código.

Extracto:

En lugar de escribir muchos comentarios para explicar los comportamientos sutiles de su programa, ¿por qué no reestructurar sus lógicas para que sean evidentes? En lugar de documentar lo que hace un método, ¿por qué no elegir un nombre claro para ese método? En lugar de etiquetar su código para indicar un trabajo sin terminar, ¿por qué no lanzar una excepción NotImplementedException ()? En lugar de preocuparse por si sus comentarios suenan lo suficientemente educados para su jefe, sus colegas o cualquiera que lea el código, ¿por qué no deja de preocuparse por no escribirlos?

Cuanto más claro sea el código, más fácil será mantenerlo, ampliarlo, trabajar en él en ediciones futuras. Cuanto menos olor tenga su código, menor será la necesidad de comentarlo. Cuantos más comentarios, mayor es el costo de mantenimiento.


¿Has oído hablar del proyecto "WEB" de Donald Knuth para implementar su concepto de programación literaria ? Es más que un código autodocumentado; es más como documentación que se puede compilar y ejecutar como código. Aunque no sé cuánto se usa hoy.


Cuando lees un "código de auto-documentación", ves lo que está haciendo, pero no siempre puedes adivinar por qué lo está haciendo de esa manera en particular.

Hay toneladas de restricciones no relacionadas con la programación, como lógica de negocios, seguridad, demandas de los usuarios, etc.

Cuando se hace el mantenimiento, la información de backgorund se vuelve muy importante.

Solo mi pizca de sal ...


La idea detrás del código de "auto-documentación" es que la lógica real del programa en el código es lo suficientemente clara como para explicar a cualquiera que lea el código, no solo lo que el código está haciendo, sino también la razón por la que lo está haciendo.

En mi opinión, la idea de un verdadero código de auto-documentación es un mito. El código puede indicar la lógica detrás de lo que está sucediendo, pero no puede explicar por qué se está haciendo de cierta manera, especialmente si hay más de una manera de resolver un problema. Por esa sola razón nunca puede reemplazar código bien comentado .


El código de auto documentación es una opción fácil para salir del problema, ya que con el tiempo el código, el comentario y la documentación divergen. Y es un factor disciplinario escribir código claro (si eres tan estricto contigo mismo).

Para mí, estas son las reglas que trato de seguir:

  • El código debe ser lo más fácil y claro posible de leer.
  • Los comentarios deberían explicar los motivos de las decisiones de diseño que tomé, como: ¿por qué utilizo este algoritmo, o las limitaciones que tiene el código, como: no funciona cuando ... (esto debe manejarse en un contrato / aserción en el código) (generalmente dentro de la función / procedimiento).
  • La documentación debe enumerar el uso (términos de llamada), efectos secundarios, valores de retorno posibles. Se puede extraer del código usando herramientas como jDoc o xmlDoc. Por lo tanto, generalmente está fuera de la función / procedimiento, pero cerca del código que describe.

Esto significa que los tres medios de documentar el código en vivo juntos y, por lo tanto, es más probable que se modifiquen cuando el código cambie, pero no se superponen en lo que expresan.


Un par de razones por las que los comentarios adicionales además del código pueden ser más claros:

  • El código que estás viendo se generó automáticamente, y por lo tanto, cualquier edición del código podría ser eliminada la próxima vez que se compile el proyecto
  • Una implementación menos que simple se cambió por una ganancia de rendimiento (desenrollar un bucle, crear una tabla de búsqueda para un cálculo costoso, etc.)

Por un lado, considere el siguiente fragmento de código:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

En este ejemplo, tiene 5 líneas de comentarios por 3 líneas de código. Peor aún: los comentarios no agregan nada que no puedas ver al leer el código. Si tiene 10 métodos como este, puede obtener 'ceguera de comentarios' y no notar el método que se desvía del patrón.

Si por supuesto, una mejor versión hubiera sido:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Aún así, por código trivial prefiero no tener comentarios. La intención y la organización en general se explican mejor en un documento separado fuera del código.


Alguien dijo una vez

1) Solo escribe comentarios para el código que es difícil de entender.
2) Trate de no escribir código que sea difícil de entender.


Creo que es importante cuestionar si una línea de código en particular se autodocumenta, pero al final, si no entiendes la estructura y la función de una porción de código, la mayoría de las veces los comentarios no te ayudarán. Tomemos, por ejemplo, el fragmento de código "comentado correctamente" de amdfan:

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Este código está bien, pero lo siguiente es igualmente informativo en la mayoría de los sistemas de software modernos, y reconoce explícitamente que el uso de un cálculo newtoniano es una opción que se puede modificar si algún otro paradigma físico fuera más apropiado:

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

En mi experiencia personal, hay muy pocas situaciones de codificación "normales" en las que absolutamente necesita comentarios. ¿Con qué frecuencia terminas rodando tu propio algoritmo, por ejemplo? Básicamente, todo lo demás es una cuestión de estructurar su sistema para que un programador pueda comprender las estructuras en uso y las elecciones que llevaron al sistema a usar esas estructuras particulares.


Creo que el código de auto-documentación es un buen reemplazo para comentar. Si necesita comentarios para explicar cómo o por qué el código es como es, entonces tiene una función o nombres de variables que deben modificarse para ser más explicativos. Puede depender del programador si compensará el déficit con un comentario o cambiará el nombre de algunas variables y funciones y el código de refactorización.

Sin embargo, realmente no puede reemplazar su documentación, porque la documentación es lo que le da a otros para explicar cómo usar su sistema, en lugar de cómo hace las cosas.

Edición: Yo (y probablemente todos los demás) probablemente debería tener la disposición de que una aplicación de Procesamiento de señal digital (DSP) debe estar muy bien comentada. Esto se debe principalmente a que las aplicaciones DSP son esencialmente 2 para bucles alimentados con arrays de valores y agrega / multiplica / etc dichos valores ... para cambiar el programa, cambie los valores en una de las matrices ... necesita un par de comentarios para decir qué lo estás haciendo en ese caso;)


En orden:

  • El código de auto-documentación es un código que expresa claramente su intención al lector.
  • No completamente. Los comentarios siempre son útiles para los comentarios sobre por qué se eligió una estrategia particular. Sin embargo, los comentarios que explican lo que está haciendo una sección de código son indicativos de un código que no es lo suficientemente autodocumentado y podrían usar cierta refactorización.
  • Los comentarios mienten y se hacen obsoletos. El código siempre dice que es más probable que diga la verdad.
  • Nunca he visto un caso donde el código no pudiera ser suficientemente claro sin comentarios; sin embargo, como dije antes, a veces es necesario / útil incluir comentarios sobre el por qué .

Es importante tener en cuenta, sin embargo, que el verdadero código de auto-documentación requiere mucha autodisciplina y disciplina de equipo. Tienes que aprender a programar de forma más declarativa, y debes ser muy humilde y evitar el código "inteligente" a favor de un código que es tan obvio que parece que cualquiera podría haberlo escrito.