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


258

Tengo un colega que insiste en que su código no necesita comentarios, es "autodocumentado".

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 autodocumentado 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 autodocumentado?
  • ¿Puede realmente reemplazar el código bien comentado y documentado?
  • ¿Hay situaciones en las que es mejor que un código bien documentado y comentado?
  • ¿Hay ejemplos en los que el código no puede autodocumentarse sin comentarios?

Tal vez son solo mis propias limitaciones, pero no veo cómo puede ser una buena práctica.

Esto no pretende ser un argumento, por favor, no mencione las razones por las cuales el 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. Comienza una nueva pregunta si es necesario, pero no discutas aquí.

¡Guau, 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 de cualquier otra respuesta aquí.

Además, aquellos de ustedes que están argumentando en contra del código autodocumentado, esto es principalmente para ayudarme a comprender la perspectiva (es decir, los aspectos positivos) de los evangelistas autocodificadores de código. Espero que otros te denigren si no te mantienes en el tema.


118
¿Sabes lo que realmente me impresiona? No estás de acuerdo con el tipo, pero pides entenderlo, no por más municiones contra él.
kajaco

14
Como historia de un caso extremadamente opuesto, tengo un compañero de trabajo que escribe toneladas de documentación: en cada archivo cpp incluye un manual con al menos un par de docenas de páginas sobre la implementación y el uso de las funciones proporcionadas. Sin embargo, ella escribe funciones desastrosamente largas y complicadas (funciones individuales con 8000 líneas de código), identificadores contra-intuitivos para variables y funciones, etc. comenta cualquier día, siempre que su código esté bien organizado con pequeñas funciones que sean fáciles de entender.
stinky472


1
En resumen, se pueden evitar la mayoría de los comentarios que explican cómo funciona el código y hacer que el código se auto documente a ese respecto. Pero a menudo también es necesario explicar por qué el código funciona de la manera en que lo hace, por ejemplo, cuando se soluciona una limitación en una biblioteca. Por lo general, necesita comentarios para explicar el por qué.
Lutz Prechelt

2
Solía ​​trabajar con alguien que comentaba en exceso todo, pero generalmente con comentarios inútiles, como i++; // increment i, pero sin explicación sobre por qué i debería incrementarse en ese punto de la función.
nnnnnn

Respuestas:


177

En mi opinión, cualquier código debe ser autodocumentado. En un buen código auto documentado, no tiene que explicar cada línea porque cada identificador (variable, método, clase) tiene un nombre semántico claro . Tener más comentarios de los necesarios 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 se auto documenta 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 en un directorio, prueba si el tamaño del archivo es mayor de 10 MB, rendimiento de retorno si es verdadero )

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 debería haber comentarios, sino que no debería 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" tarda más en entenderse que el código comentado, en realidad no es autodocumentado.



14
Punto nr. 3 debe ser parte del punto nr. 1 En mi humilde opinión, si un método es tan complejo que requiere comentarios de alta abstracción para varios bloques de código, cada uno de esos bloques de código debería ser un método nuevo.
Bjarke Freund-Hansen

10
+1 para "no significa que no debería haber comentarios", que parece ser la opinión de algunas personas.
Skurmedel

44
Todavía no es necesario comentar eso: public static Collection <File> filesGreaterThan (Ruta del archivo, int sizeInBytes);
Trylks 01 de

66
Una buena regla general para mí es que los comentarios nunca deberían explicar QUÉ está haciendo el código, sino que pueden usarse para explicar POR QUÉ lo está haciendo. En otras palabras, comente un bloque de código para explicar por qué está allí, no cómo funciona. Si puede factorizar el bloque en su propio método claramente nombrado, entonces eso es aún mejor. De eso se trata el código autodocumentado.
Mel

387

Bueno, dado que se trata de comentarios y código, veamos un código real. Compare este código típico:

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

Para este código autodocumentado, 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 haberse nombrado descriptivamente, y los resultados de una operación se resumen cuando podemos ver claramente qué es la operación. Preferiría el segundo ejemplo auto documentado a este cualquier día, y tal vez de eso está hablando su amigo 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 también es útil un comentario que detalle la metodología detrás de lo que está detrás (en este ejemplo, la ecuación).


73
Sin embargo, todo ese fragmento realmente debería estar en una función con un nombre descriptivo;)
workmad3

77
Sí, la función desplamentDueToGravity (int timeInSeconds, float gravitationalAcceleration = 9.81) me sería más fácil de leer.
Cristián Romo

18
El único comentario que extraño aquí es: ¿Por qué 5 segundos?
John Nilsson el

3
Otro voto para el nombre descriptivo de la función. No da la ecuación en sí, pero no veo que sea necesaria.
Loren Pechtel

18
¿Cuáles son las unidades de fuerza gravitacional? Existen límites para la cantidad que puede agregar a un nombre de variable. En algún momento tienes que explicar lo que estás tratando de hacer . A menudo esto no es obvio , por lo que debes comentar el código. Es decir basura absoluta código es autodocumentado, es sólo auto descriptiva .
Nick

172

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 para él explicar la intención , que es el aspecto más vital de los comentarios. Si está escrito correctamente, ya sabemos lo que hace el código, ¡solo necesitamos saber por qué demonios lo hace!


Convenido. Aunque ocasionalmente incluso el mejor código puede ocultar cuál es su efecto final, esto se maneja respondiendo el por qué en los comentarios. Como en "¿Por qué cambiaste esas 5 variables de esa manera?"
Sam Erwin

My 2 Cent: ¿no es el caso [Unidad, Especificación, Comportamiento,] una respuesta a "por qué demonios"? Luego, puede leer el caso de prueba y se le debe dar la intención de por qué.
Jonke

2
Creo que esos pueden responder a los por qué de alto nivel, pero no explican cosas como "estoy rellenando esta estructura con tantos bytes, para que se mantenga alineada correctamente cuando se transmite a alguna plataforma oscura". Para ellos, los comentarios de código son la mejor manera de preservar el conocimiento institucional.
tsellon

Y por lo tanto, debe comentar donde la intención no es inequívoca dado el código en sí.
Draemon

2
@tsellon, su especificación automatizada puede decirle eso, y lo bueno es que el código verifica el código de implementación. Entonces, si la implementación cambia de alguna manera, la especificación se rompe. Que lindo es eso? ¿Comentarios que lo alertan cuando el código de implementación ya no está haciendo lo que el comentario especificó?
Pragmatic Agilist

96

Alguien dijo una vez

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


28
Lo que parece trivial para que usted comprenda al momento de escribir el código, de hecho, puede ser muy difícil de entender para otra persona más tarde, incluso si esa otra persona es de hecho usted mismo en unos pocos meses / años.
Anders Sandvig

15
A menudo me encuentro cosas que escribí el viernes bastante difícil de asimilar el lunes por la mañana :)
Loofer

1
lo que nos lleva a "intentar no escribir comentarios"
mustafabar

37

La idea detrás del código de "autodocumentació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 está haciendo el código sino por qué lo está haciendo.

En mi opinión, la idea del verdadero código de autodocumentació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 forma de resolver un problema. Por esa sola razón, nunca puede reemplazar el código bien comentado .


1
En mi humilde opinión, el bloque debe indicar el cómo , el nombre de la función debe indicar el por qué . Siempre que use ambos juntos, transmite tanto la intención como la implementación ... int GetBoundingBox() {return CalcContentDimensions() + this.padding + this.margin;}...
Básico

19

Creo que es relevante preguntarse si una línea de código en particular es autodocumentada, pero al final, si no comprende la estructura y la función de una porción de código, la mayoría de las veces los comentarios no ayudarán. Tomemos, por ejemplo, la porción 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 usar un cálculo newtoniano es una opción que puede modificarse si algún otro paradigma físico es 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 absolutamente se necesitan comentarios. ¿Con qué frecuencia terminas rodando tu propio algoritmo, por ejemplo? Básicamente, todo lo demás es cuestión de estructurar su sistema para que un codificador pueda comprender las estructuras en uso y las opciones que llevaron al sistema a usar esas estructuras particulares.


2
necesita más votos a favor, su ejemplo explica por qué deberíamos usar nombres de funciones para documentar la intención.
Ape-inago

16

Olvidé de dónde saqué esto, pero:

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


26
Basura. Los buenos comentarios en código absolutamente tienen su lugar. Tome el ejemplo de elegir entre dos métodos igualmente correctos para resolver un problema. Un comentario que explica por qué se eligió un método sobre el otro es extremadamente significativo y nunca se puede obtener del código en sí.
Scott Dorman

77
Si hay dos métodos IGUALMENTE CORRECTOS, ¿importa por qué eligió uno sobre el otro?
EBGreen

1
Sí, igualmente correcto no significa exactamente lo mismo. Un método puede ser más rápido en algunas situaciones que otro.
Ikke

Entonces, si su criterio de decisión es la velocidad, no son IGUALMENTE CORRECTOS. No digo que los comentarios sean malos. Solo que son necesarios porque actualmente no existe un lenguaje de programación que sea tan claro e inequívoco que cualquiera pueda mirar el código y conocer instantáneamente la intención del código.
EBGreen

9
No creo que la gente entienda esa cita de la misma manera que yo. Supongo que significa que debe esforzarse por escribir siempre un código que sea tan claro que no necesite ser comentado, sino que tenga que aceptar que es un ideal que nunca funciona en la realidad.
EBGreen

14

En primer lugar, es bueno saber 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 "autodocumentación" como excusa para ser demasiado vago como para comentar su código.

El código autodocumentado es un código que no requiere comentarios de texto libre para que un lector informado comprenda lo que está haciendo. Por ejemplo, este fragmento de código es autodocumentado:

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 tiene problemas para seguir el código de su colega, entonces haría bien en reevaluar 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 la autodocumentación del código.

El mejor argumento que he visto para escribir "código autodocumentado" es que evita el problema de que los comentarios de texto libre no concuerden 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 por sí mismo, no puede explicar por qué se está haciendo algo de cierta manera.


14

El código autodocumentado es un buen ejemplo de "SECO" (no se repita). No duplique información en los comentarios que está, o puede estar, en el código mismo.

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

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

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

Etc.

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

Esto no significa que no tenga ningún comentario, hay información que no puede incluir 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í, y cada uno agrega un valor explicativo único sin duplicar la información del otro.


44
Una excepción: malos programadores. He visto comentarios que dicen que el código está haciendo algo que no es. Luego me pregunto: ¿debería arreglar el código o el comentario?
Guge

No se pueden superar los nombres de métodos en Objective-C. :)

13

El código de autodocumentació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 evaluadores o para generar documentación / archivos de ayuda.

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


9

En orden:

  • El código autodocumentado es un código que expresa claramente su intención al lector.
  • No completamente. Los comentarios siempre son útiles para comentar 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 se documenta por sí mismo y que podría necesitar una refactorización.
  • Los comentarios mienten y quedan desactualizados. El código siempre dice que es más probable que diga la verdad.
  • Nunca he visto un caso en el que el código no se pueda aclarar lo suficiente sin comentarios; sin embargo, como dije antes, a veces es necesario / útil incluir comentarios sobre por qué .

Sin embargo, es importante tener en cuenta que el código verdaderamente autodocumentado requiere mucha disciplina personal y de equipo. Tienes que aprender a programar de manera más declarativa, y debes ser muy humilde y evitar el código "inteligente" a favor del código que es tan obvio que parece que cualquiera podría haberlo escrito.


Agregaré una selección de liendres aquí. El código no siempre "dice la verdad". El código puede ser engañoso y ofuscar sus intenciones muy fácilmente. Por ejemplo, una variable o método con un nombre incorrecto puede mentir tanto como un comentario desactualizado.
Wedge

Los nombres de los métodos pueden mentir y también pueden estar desactualizados.
Calmarius

7

Cuando lee un "código autodocumentado", ve lo que está haciendo, pero no siempre puede adivinar por qué lo hace de esa manera en particular.

Hay toneladas de restricciones que no son de programación, como lógica de negocios, seguridad, demandas de los usuarios, etc.

Cuando realiza el mantenimiento, esa información de fondo se vuelve muy importante.

Solo mi pizca de sal ...


6

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, tiene 5 líneas de comentarios por 3 líneas de código. Peor aún: los comentarios no agregan nada que no pueda ver al leer el código. Si tiene 10 métodos como este, puede obtener 'ceguera de comentarios' y no notar el único 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í, para el código trivial prefiero no tener comentarios. La intención y la organización general se explican mejor en un documento separado fuera del código.


Puede parecer trivial documentar getters y setters, pero creo que hay un medio feliz entre tener un comentario inútil y no tener ningún comentario. El punto de muchos comentarios de Javadoc es informar a alguien que no puede o no tiene la inclinación de mirar el código en el método.
James McMahon el

6

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

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

Muy en desacuerdo. Lo que hace una rutina debería ser obvio por el nombre. Cómo lo hace debería ser obvio por el código de implementación. Se debe documentar por qué la implementación se escribió tal como está .
Anthony Manning-Franklin

5

Una cosa que es posible que desee señalar a su colega es que no importa cuán auto documentado sea su código, si se consideran y descartan otros enfoques alternativos, esa información se perderá a menos que él 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ó no hacerlo, y los comentarios de código tienen más probabilidades de sobrevivir con el tiempo.


Tomas esto como una regla y terminarás escribiendo un libro de texto en tu base de código ;-) Sin embargo, estoy de acuerdo con decisiones no obvias.
ddimitrov

@ddimitrov, esa es una buena observación. Pero como usted dice para las decisiones no obvias (y esas son generalmente las que realmente requieren documentación de todos modos) es una buena práctica.
Onorio Catenacci

¡Documente el código que no fue escrito! :)
Tony

5

En una empresa donde trabajaba, uno de los programadores tenía lo siguiente pegado en 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".


4

El código autodocumentado normalmente usa nombres de variables que coinciden exactamente con lo que está haciendo el código para que sea fácil de entender lo que está sucediendo

Sin embargo, dicho "código autodocumentado" nunca reemplazará los comentarios. A veces, el código es demasiado complejo y el código autodocumentado no es suficiente, especialmente en lo que se refiere al mantenimiento.

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


Luego refactorícelo hasta que esté más claro. Creo firmemente que no hay nada que el código no pueda decir con bastante claridad.
Tigraine

44
Excepto por qué se eligió una implementación específica, un algoritmo o una fórmula en lugar de otra igualmente correcta. Nunca puede describir por qué se hizo una elección en código, solo cuál fue esa elección.
Scott Dorman el

1
@scott: podría poner ambas opciones en una clase más amplia y dejar la otra sin implementar con un comentario sobre ... oh, espera.
Ape-inago

4

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

La premisa es simple: dado que el código debe ser entendido por un humano y los comentarios simplemente son 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 de los requisitos del lenguaje de programación. , para el lector humano y código puro para el compilador.

Las herramientas de programación Literate 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 luego 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 en una biblioteca (Donald E. Knuth, Literate Programming, Stanford, California: Center for the Study of Language and Information, 1992, CSLI Lecture Notes, no. 27), debe leerlo.

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


Eso es en realidad lo opuesto al código autodocumentado. Texto para el humano, código para la máquina. ¿Y qué idioma debe ser el código? Montaje por supuesto. Los humanos no necesitan leerlo, ¿verdad? ¡Solo necesitan escribirlo!
Guge

4

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 asamblea. 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í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 poner más estructura que el texto. El texto solo funciona con contexto, lo que damos por sentado cuando usamos texto. El contexto en el código fuente siempre es explícito. Piense "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 usan más inferencia e intentan eliminar esa redundancia.

Los nombres de tipos, nombres de métodos y nombres de variables no son necesarios para las computadoras. Los usamos para hacer referencia. 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 debería ser legible para nosotros. Si somos buenos en semántica donde está permitido y buenos 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 acecha en cada proyecto, siempre tienes que decidir dónde poner la complejidad y qué camellos tragar. Esos son los lugares para usar los comentarios.


3

El código de autodocumentación es una opción sencilla para salir del problema, ya que con el tiempo el código, los comentarios y la documentación divergen. Y es un factor disciplinario escribir un 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 de leer posible.
  • Los comentarios deben dar razones para las decisiones de diseño que tomé, como: por qué uso 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) dentro de la función / procedimiento).
  • La documentación debe enumerar el uso (conversiones de llamadas), efectos secundarios, posibles valores de retorno. Se puede extraer del código utilizando 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 para documentar el código viven juntos y, por lo tanto, es más probable que cambien cuando el código cambia, pero no se superponen en lo que expresan.


3

El verdadero problema con el llamado código autodocumentado es que transmite lo que realmente hace. Si bien algunos comentarios pueden ayudar a alguien a comprender 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 es directamente evidente 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 poder 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.


3

Creo que el código autodocumentado 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 deberían modificarse para ser más explicativos. Sin embargo, puede depender del codificador si va a compensar el déficit con un comentario o cambiar el nombre de algunas variables y funciones y refactorizar el código.

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.

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. Esto se debe principalmente a que las aplicaciones DSP son esencialmente 2 para bucles alimentados con matrices 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é que estás haciendo en ese caso;)


Entonces, ¿un nombre de función o variable proporcionará suficiente contexto trivialmente claro para explicar por qué se eligió una implementación sobre otra dada dos o más formas igualmente correctas de resolver un problema?
Scott Dorman

3

Al escribir código matemático, a veces me parece útil escribir comentarios largos, similares a 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 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.

Ahora, por supuesto, este tipo de medida extrema no es necesaria en la mayoría de los casos. Creo que la moraleja de la historia es: diferentes códigos requieren diferentes cantidades de documentación. Algún código puede escribirse 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 sea necesario ...


3

Yo diría, como muchos de ustedes, que para ser verdaderamente autodocumentado, el código debe mostrar algún tipo de intención. Pero me sorprende que nadie haya mencionado BDD todavía: Behavior Driven Development . Parte de la idea es que tenga pruebas automatizadas (código) que expliquen la intención de su código, que es muy difícil de hacer obvio de lo contrario.

Buen modelado de dominio 
+ buenos nombres (variabes, métodos, clases) 
+ ejemplos de código (pruebas unitarias de casos de uso) 
= software de autodocumentación 

2

Un par de razones por las cuales 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 modificada la próxima vez que se compile el proyecto.
  • Se cambió una implementación menos que sencilla por una ganancia de rendimiento (desenrollar un bucle, crear una tabla de búsqueda para un cálculo costoso, etc.)

2

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 cómo es importante y esto no siempre se captura en el código de autodocumentación. get / set no, estos son obvios, pero el cálculo, la recuperación, etc., deben explicarse por qué.

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

BisecciónBúsqueda

Búsqueda binaria

BinaryChop

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


2

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

Por lo general, es fácil escribir código que documenta por sí mismo 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 comprende 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 contar el libro completo en su título, por lo que las principales abstracciones de su sistema aún deben documentarse, así como los algoritmos complejos, los contratos de métodos no triviales y los artefactos.

Si el código que produce su colega está realmente documentado, afortunadamente usted y él. Si cree que el código de sus colegas necesita comentarios, es necesario. Simplemente abra el lugar más trivial en él, léalo una vez y vea si entendió todo o no. Si el código está auto documentado, entonces debería hacerlo. Si no, haga una pregunta a su colega al respecto, después de que él 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 le explica todo lo que necesita entender, necesita comentarios


2

La mayoría de la documentación / comentarios sirven para ayudar a futuros desarrolladores / mejoradores de código, por lo tanto, hacen que el código sea mantenible. La mayoría de las veces terminamos regresando a nuestro módulo más adelante para agregar nuevas funciones u optimizar. En ese momento, sería más fácil entender el código simplemente leyendo los comentarios que pasando por numerosos puntos de interrupción. Además, preferiría pasar el tiempo pensando en una nueva lógica que descifrar la existente.


1

Creo que a lo que él podría llegar es que si los comentarios explican lo que está haciendo el código, deberían reescribirse para tener claro cuál es su intención. Eso es lo que quiere decir con código autodocumentado. A menudo, esto puede significar simplemente dividir la función larga en partes lógicas más pequeñas con un nombre descriptivo de la función.

Eso no significa que el código no deba ser comentado. Significa que los comentarios deben proporcionar una razón por la cual el código está escrito de la manera en que está.


1

Creo que siempre debe esforzarse por lograr un código de autodocumentación porque facilita la lectura del código. Sin embargo, también debes ser pragmático sobre las cosas.

Por ejemplo, generalmente agrego un comentario a cada miembro de la clase (uso comentarios de documentación para esto). Esto describe lo que se supone que debe hacer el miembro, pero no cómo lo hace. Encuentro que cuando estoy leyendo el código, particularmente el código antiguo, esto me ayuda a recordar rápidamente para qué es el miembro y también me resulta más fácil que leer el código y resolverlo, particularmente si el flujo de código salta bastante .

Esta es sólo mi opinión. Sé de muchas personas que trabajan sin comentarios y dicen que consideran que esto no es un problema. Sin embargo, le pregunté a alguien sobre un método que escribieron seis meses antes y han tenido que pensar durante unos minutos para decirme exactamente lo que hizo. Esto no es un problema si se comenta el método.

Finalmente, debe recordar que los comentarios son igualmente parte del sistema como el código. A medida que refactoriza y cambia la funcionalidad, también debe actualizar sus comentarios. Este es un argumento en contra del uso de comentarios, ya que son peores que inútiles si son incorrectos.

Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.