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

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.

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.

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

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!

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.

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 .

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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

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.

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

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.

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.

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.

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

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

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 

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

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.

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

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.

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

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.