documentation - example - ¿Qué es el código de auto-documentación y puede reemplazar el código bien documentado?
params comments c# (30)
¿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.
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.
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.
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).
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;)
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.
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 ...
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 ...
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.
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.
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!
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.
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í .
En mi opinión, cualquier código debería ser auto-documentado. En un buen código autodocumentado, no tiene que explicar cada una de las líneas porque cada identificador (variable, método, clase) tiene un nombre semántico claro. Tener más comentarios de los necesarios en realidad hace que sea más difícil (!) Leer el código, así que si su colega
- escribe comentarios de documentación (Doxygen, JavaDoc, comentarios XML, etc.) para cada clase, miembro, tipo y método Y
- comenta claramente cualquier parte del código que no sea auto-documentada Y
- escribe un comentario para cada bloque de código que explica la intención, o lo que hace el código en un nivel de abstracción más alto (es decir, encuentra todos los archivos de más de 10 MB en lugar de recorrer todos los archivos de un directorio, comprueba si el tamaño del archivo es mayor que 10 MB, rendimiento si es cierto )
Su código y documentación está bien, en mi opinión. Tenga en cuenta que el código auto documentado no significa que no debe haber comentarios, sino que no debe haber comentarios innecesarios. Sin embargo, la cuestión es que al leer el código (incluidos los comentarios y los comentarios de la documentación) se debe obtener una comprensión inmediata de lo que hace el código y por qué. Si el código de "autodocumentación" lleva más tiempo que el código comentado, no es realmente autodocumentado.
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 quees 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.
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.
En una compañía donde trabajé, uno de los programadores tenía lo siguiente pegado a la parte superior de su monitor.
"Documente su código como si la persona que lo mantiene es un maníaco homocida que sabe dónde vive".
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.
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 .
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 corriendo el montaje. Los lenguajes de programación son para nuestro beneficio. No queremos escribir ensamblaje. Necesitamos entender lo que estamos escribiendo. La programación es sobre escribir código.
¿Deberías poder leer lo que escribes?
El código fuente no está escrito en lenguaje humano. Se ha probado (por ejemplo, FORTRAN) pero no es completamente exitoso.
El código fuente no puede tener ambigüedad. Es por eso que tenemos que ponerle más estructura que a la del texto. El texto solo funciona con el contexto, que damos por sentado cuando usamos texto. El contexto en el código fuente siempre es explisit. Piensa "usando" en C #.
La mayoría de los lenguajes de programación tienen redundancia para que el compilador nos pueda atrapar cuando no somos coherentes. Otros lenguajes usan más inferencia y tratan de eliminar esa redundancia.
Los nombres de tipos, nombres de métodos y nombres de variables no son necesarios para las computadoras. Son utilizados por nosotros para referenciar. El compilador no entiende la semántica, eso es para que lo usemos.
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 nos sea legible. Si somos buenos en semántica donde está permitido y bueno en estructurar el código, el código fuente debería ser fácil de leer incluso para nosotros. El mejor código no necesita comentarios.
Pero la complejidad se esconde en cada proyecto, siempre hay que decidir dónde colocar la complejidad y qué camellos tragar. Esos son los lugares para usar comentarios.
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 :-)
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.
Olvidé de dónde obtuve esto, pero:
Cada comentario en un programa es como una disculpa para el lector. "Lamento que mi código sea tan opaco que no lo entiendas mirándolo". Solo tenemos que aceptar que no somos perfectos, pero debemos esforzarnos por ser perfectos y seguir disculpándonos cuando sea necesario.
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.
Una cosa que tal vez desee señalar a su colega es que no importa qué tan autodocumentado 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 tan importante saber que se consideró una alternativa y por qué se decidió en contra y los comentarios de código tienen más probabilidades de sobrevivir con el tiempo.
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 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.
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.)
Para mí, leer el código que necesita comentarios es como leer un texto en el 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.
Por lo general, es fácil escribir código que auto-documenta 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, debe intentar organizar su 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 lograr su objetivo. De todos modos, no puede indicar el libro completo en su título, por lo que las principales abstracciones de su sistema aún deben documentarse, así como algoritmos complejos, contratos de métodos no triviales y artefactos.
Si el código que produce su colega es realmente auto-documentado, afortunado usted y él. Si crees que el código de tus colegas necesita comentarios, necesita. Simplemente abra el lugar más no trivial en él, léalo una vez y vea si entendió todo o no. Si el código es auto documentado, entonces debería hacerlo. Si no, pregúntele a su colega una pregunta al respecto, después de que él le dé una respuesta, pregunte por qué esa respuesta no se documentó de antemano en los comentarios o el código. Puede afirmar que el código es un documento personal 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 una comprensión de su código y este no le explica todo lo que necesita entender, necesita comentarios
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.
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