¿Qué es el código auto-documentante y puede reemplazar el código bien documentado? [cerrado]

Bueno, ya que se trata de comentarios y código, echemos un vistazo a algún código real. Compare 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 utilizan 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 cuál es la operación. Preferiría el segundo ejemplo auto-documentado a este cualquier día, y tal vez eso es de lo que su amigo está hablando cuando dice código auto-documentado.

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

El código en sí siempre va a ser la explicación más actualizada de lo que hace tu código, pero en mi opinión es muy difícil para él explicar la intención, que es el aspecto más vital de los comentarios. Si está escrito correctamente, ya sabemos qué hace el código, solo necesitamos saber por qué en la tierra lo hace!

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 es difícil de entender.

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 por qué lo está haciendo.

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

Creo que es relevante cuestionar si una línea de código en particular se documenta por sí misma, pero al final si no entiendes la estructura y función de un fragmento de código, la mayoría de las veces los comentarios no van a ayudar. Tomemos, por ejemplo, el fragmento de código "correctamente comentado" 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 puede ser alterado debería algún otro paradigma físico ser más apropiado:

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

En mi propia experiencia personal, hay muy pocas situaciones de codificación "normales" en las que necesite absolutamente 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 codificador pueda comprender las estructuras en uso y las opciones que impulsaron al sistema a usar esas estructuras particulares.

Se me olvida de dónde saqué esto, pero:

Cada comentario en un programa es como una disculpa al lector. "Siento que mi código sea tan opaco que no puedas entenderlo mirándolo". Solo tenemos que aceptar que no somos perfectos, pero nos esforzamos por ser perfectos y seguir disculpándonos cuando lo necesitamos.

El código autodocumentado es un buen ejemplo de "SECO" (No Te Repitas). No dupliques la información en los comentarios que está, o puede estar, en el código en sí.

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

En lugar de explicar lo que hace un fragmento corto de código, extráigalo en un método y dale un nombre descriptivo (tal vez una versión abreviada del texto de tu comentario).

En lugar de explicar lo que hace una prueba complicada, extraiga eso en un método también y darle un buen nombre.

Etc.

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

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

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 entendido por todos en el equipo.

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

El código autodocumentado + los comentarios necesarios ayudarán en gran medida a las personas de todos los equipos.

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

El código auto-documentante es un código que no requiere comentarios de texto libre para que un lector informado entienda lo que está haciendo. Por ejemplo, este fragmento de código se documenta automáticamente:

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 cualquier otra persona 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 lenguaje y las bibliotecas que se utilizan para llamar a código de auto-documentación.

El mejor argumento que he visto para escribir "código de auto-documentación" es que evita el problema del comentario de texto libre no estar de acuerdo con el código tal como está escrito. La mejor crítica es que mientras el código puede describir qué y cómo está haciendo por sí mismo, no puede explicar por qué algo se está haciendo de cierta manera.

En orden:

• El código auto-documentante es un código que expresa claramente su intención al lector.
• No del todo. Los comentarios siempre son útiles para comentar por qué se eligió una estrategia en particular. Sin embargo, los comentarios que explican lo que está haciendo una sección de código son indicativos de código que no se documenta lo suficiente y podrían usar alguna refactorización..
• Los comentarios mienten y se vuelven obsoletos. Código siempre dice es más probable que di la verdad.
• Nunca he visto un caso en el que el qué del 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 código que realmente se documenta a sí mismo requiere mucha disciplina personal y de equipo. Tienes que aprender a programar de forma más declarativa, y tienes que ser muy humilde y evitar el código "inteligente" en favor del código que es tan obvio que parece que cualquiera podría haberlo escrito.

Por un lado, considere el siguiente fragmento:

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

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

Si por supuesto, una versión mejor habría 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í, para código trivial prefiero no tener comentarios. La intención y el la organización general se explica mejor en un documento separado fuera del código.

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

Hay toneladas de limitaciones no programáticas como lógica de negocios, seguridad, demandas de los usuarios, etc.

Cuando haces mantenimiento, esa información de backgorund se vuelve muy importante.

Sólo mi pizca de sal...

Una cosa que tal vez desee señalar a su colega es que no importa cuán auto-documentante sea su código, si se consideraron y descartaron otros enfoques alternativos, esa información se perderá a menos que comente el código con esa información. A veces es igual de importante saber que se consideró una alternativa y por qué se decidió en contra y es más probable que los comentarios de código sobrevivan con el tiempo.

¿Has oído hablar del proyecto "WEB" de Donald Knuth para implementar su concepto de Programación Alfabetizada? Es más que código auto-documentante; es más como documentación que puede ser compilada y ejecutada como código. Sin embargo, no se cuánto se usa hoy en día.

La diferencia está entre "qué" y "cómo".

• Debe documentar "lo que" hace una rutina.
• No debe documentar "cómo" lo hace, a menos que casos especiales (por ejemplo, se refieran a un documento de algoritmo específico). Eso debe ser auto-documentado.

En una empresa donde trabajé, uno de los programadores tenía lo siguiente pegado en la parte superior de su monitor.

"Documente su código como la persona que lo mantiene es un maníaco homocida que sabe dónde vive."

El punto de vista de que el código se documenta a sí mismo me vuelve loco. Una línea particular de código o un sub algoritmo puede ser de hecho auto documentarse, pero su propósito en el picutre mayor simplemente no lo es.

Me frustré tanto con esto hace un mes o dos que escribí un post completo en el blog describiendo mi punto de vista. Publicar aquí.

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

Sin embargo, tal "código auto-documentante" nunca reemplazará los comentarios. A veces el código es demasiado complejo y el código de auto-documentación no es suficiente, especialmente en el camino de la mantenibilidad.

Una vez tuve un profesor que creía firmemente en esta teoría De hecho, lo mejor que recuerdo que dijo es " Los comentarios son para sissies "
Tomó a todos por sorpresa al principio, pero tiene sentido.
Sin embargo, la situación es que a pesar de que usted puede ser capaz de entender lo que está pasando en el código, pero alguien que tiene menos experiencia que usted puede venir detrás de usted y no entender lo que está pasando. Aquí es cuando los comentarios se vuelven importantes. Sé muchas veces que no creemos que sean importantes, pero hay muy pocos casos en los que los comentarios son innecesarios.

Me sorprende que nadie haya dado lugar a la "Programación Alfabetizada", una técnica desarrollada en 1981 por Donald E. Knuth de TeX y la fama de "El Arte de la Programación Informática".

La premisa es simple: dado que el código tiene que ser entendido por un humano y los comentarios son simplemente desechados por el compilador, ¿por qué no dar a todos lo que necesitan - una descripción textual completa de la intención del código, sin restricciones por los requisitos del lenguaje de programación, para el lector humano y código para el compilador.

Las herramientas de programación alfabetizadas 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. El programa más tarde extrae las partes de código fuente del documento y ensambla un archivo de código.

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

Si usted puede encontrar el libro de Knuth en él en un (Donald E. Knuth, Literate Programming, Stanford, California: Center for the Study of Language and Information, 1992, CSLI Lecture Notes, no. 27.) deberías leerlo.

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

Mi punto de vista está escrito 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 su lógicas para que sean evidentes? En lugar de documentar lo que un método está haciendo, ¿por qué no elegir un nombre claro ¿por ese método? En lugar de etiquetar su código para indicar el trabajo inacabado, ¿por qué no lanzar un NotImplementedException ()? En lugar de preocuparse de si sus comentarios suenan lo suficientemente educado con su jefe, su colegas o cualquiera que lea el código, ¿por qué no dejar de preocuparse por no ¿escribiéndolos?

Cuanto más claro sea tu código, más fácil será es de mantener, extender, a trabajar en él en futuras ediciones. El menos ordorous es su código, el menos hay que comentarlo. El más los comentarios, cuanto mayor sea el costo de mantenimiento.

Me gustaría ofrecer una perspectiva más a las muchas respuestas válidas:

¿Qué es el código fuente? ¿Qué es un lenguaje de programación?

Las máquinas no necesitan código fuente. Son felices dirigiendo el montaje. Los lenguajes de programación son para nuestro beneficio. No queremos escribir asamblea. Necesitamos entender lo que estamos escribiendo. La programación se trata de escribir código.

¿Debería ser capaz de leer lo que escribe?

El código fuente no está escrito en lenguaje humano. Ha sido probado (por ejemplo FORTRAN) pero no es completamente exitoso.

El código fuente no puede tener ambigüedad. Es por eso que tenemos que poner más estructura en él que lo hacemos con el texto. El texto solo funciona con contexto, que damos por sentado cuando usamos texto. El contexto en el código fuente siempre es explícito. Piense en "usar" en C#.

La mayoría de los lenguajes de programación tienen redundancia para que el compilador pueda atraparnos cuando no somos coherentes. Otros idiomas utilizan más inferencia y tratan de eliminar eso redundancia.

Los nombres de tipos, nombres de métodos y nombres de variables no son necesarios para los equipos. Son utilizados por nosotros para referenciar. El compilador no entiende la semántica, eso es para nosotros.

Los lenguajes de programación son un puente lingüístico entre el hombre y la máquina. Tiene que ser escribible para nosotros y legible para ellos. Las demandas secundarias son que debe ser legible para nosotros. Si somos buenos en semántica donde está permitido y buenos en estructurar el código, el código fuente debe ser fácil de lea incluso para nosotros. El mejor código no necesita comentarios.

Pero la complejidad acecha en cada proyecto, siempre hay que decidir dónde poner la complejidad, y qué camellos tragar. Esos son los lugares para usar comentarios.

El código de auto-documentación es una opción fácil de exclusión del problema, que con el tiempo el código, los comentarios 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 tan fácil y claro para leer como sea posible.
• En los comentarios deben indicarse las razones para decisiones de diseño que tomé, como: por qué ¿utilizo este algoritmo, o limitaciones que tiene el código, como: hace no funciona cuando ... (esto debe ser manejado en un contrato / aserción en el código) (generalmente dentro de la función / procedimiento).
• La documentación debe enumerar el uso (llamando a converntions), lado efectos, posibles valores de retorno. Se puede extraerse del código usando herramientas como jDoc o xmlDoc. Se por lo tanto, por lo general está fuera de la función/procedimiento, pero cerca de la código que describe.

Esto significa que los tres medios de documentación de código viven muy juntos y, por lo tanto, es más probable que se cambien cuando el código cambia, pero no se superponen en lo que expresan.

El verdadero problema con el llamado código de auto-documentación es que transmite lo que realmente hace. Mientras que algunos comentarios pueden ayudar a alguien a entender mejor el código (por ejemplo, pasos de algoritmos, etc.) es hasta cierto punto redundante y dudo que convenza a su par.

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

Ser capaz de determinar que un código hace X de un vistazo rápido es mucho más fácil que ser capaz de determinar que un código no hace Y. 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.

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 variable que deben modificarse para que sean más explicativos. Puede ser hasta el codificador en cuanto a si va a compensar el déficit con un comentario o cambiar el nombre de algunas variables y funciones y refactorización de código, aunque.

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

Editar: 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) debería estar muy bien comentada. Eso es principalmente porque las aplicaciones DSP son esencialmente 2 para bucles alimentados con matrices de valores y agrega/multiplica/etc dichos valores... para cambiar el programa se cambian los valores en una de las matrices... necesita un par de comentarios para decir lo que está haciendo en ese caso ;)

Al escribir código matemático, a veces me ha resultado útil escribir comentarios largos, similares a ensayos, explicando las matemáticas, las convenciones notacionales que usa el código y cómo todo encaja. Estamos hablando de cientos de líneas de documentación, aquí.

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

Ahora, por supuesto este tipo de la medida extrema no es necesaria en la mayoría de los casos. Creo que la moraleja de la historia es: un código diferente requiere diferentes cantidades de documentación. Algún código se puede escribir tan claramente que no necesita comentarios! ¡así que escríbalo claramente y no use comentarios allí!

Pero mucho código necesita comentarios para tener sentido, así que escríbalo lo más claramente posible y luego use tantos comentarios como necesite...

Yo argumentaría - como muchos de ustedes hacen - que para ser verdaderamente auto documentada, el código necesita mostrar alguna forma de intención. Pero me sorprende que nadie haya mencionado BDD todavía - Desarrollo Impulsado por el Comportamiento. Parte de la idea es que tiene pruebas automatizadas (código) que explican la intención de su código, que es tan difícil de hacer obvio de otra manera.

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

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

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

Va a estar todo en lo que el equipo valora en su documentación. Yo sugeriría que documentar por qué / intención en lugar de cómo es importante y esto no siempre se captura en el código de auto-documentación. get / set no estos son obvios, pero el cálculo, la recuperación, etc. algo del por qué debe expresarse.

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

Búsqueda de bisecciones

BinarySearch

BinaryChop

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

Para mí leer código que necesita comentarios es como leer texto en un idioma que no conozco. Veo una declaración y no entiendo qué hace ni por qué, y tengo que mirar los comentarios. Leí una frase y necesito buscar en el diccionario para entender lo que significa.

Normalmente es fácil escribir código que documente lo que hace. Para decirle por qué lo hace los comentarios son más adecuados, pero incluso aquí el código puede ser mejor. Si entiende su sistema en todos los niveles de abstracción, deberías intentar organizar tu código como

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

Donde el nombre del método refleja su intención y el cuerpo del método explica cómo logra su objetivo. De todos modos no se puede decir todo el libro en su título, por lo que las abstracciones principales de su sistema todavía tienen que ser documentados, así como algoritmos complejos, contratos de métodos no triviales y artefactos.

Si el código que tu colega produce es realmente auto-documentado - suerte tú y él. Si crees que el código de tus colegas necesita comentarios, requiere. Simplemente abra el lugar más no trivial en él, léalo una vez y vea si lo entendió todo o no. Si el código está auto-documentado - entonces usted debe. Si no, pregúntele a su colega una pregunta al respecto, después de que le dé una respuesta, pregunte por qué esa respuesta no se documentó en comentarios o código de antemano. Puede afirmar que el código es un documento propio para una persona tan inteligente como él, pero de todos modos tiene que respetar a los demás miembros del equipo, si sus tareas requieren la comprensión de su código y su código no explíquele todo lo que necesita entender, necesita comentarios.