documentation - example - remarks c#




¿Qué es el código de auto-documentación y puede reemplazar el código bien documentado? (20)

¿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.


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 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 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.


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 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.


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.

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 :-)


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.


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.


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.