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

StackOverflow https://stackoverflow.com/questions/209015

  •  03-07-2019
  •  | 
  •  

Pregunta

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 en 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 de auto documentación?
  • ¿Puede realmente reemplazar el código bien comentado y documentado?
  • ¿Hay situaciones en las que 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 los motivos por los que los códigos bien comentados y documentados son de alta prioridad. Existen muchos recursos que lo muestran, 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í.

También, 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 otros te voten si no te mantienes en el tema.

¿Fue útil?

Solución

En mi opinión, cualquier código debería autodocumentarse. En un buen código autodocumentado, no tiene que explicar cada línea porque cada identificador (variable, método, clase) tiene un nombre claro semántico . Tener más comentarios de los necesarios en realidad hace que sea más difícil (!) Leer el código, por lo 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 documenta a sí misma 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 recorre todos los archivos en un directorio, compruebe si el tamaño del archivo es superior a 10 MB, devuelva el rendimiento si es verdadero )

su código y documentación están bien, en mi opinión. Tenga en cuenta que el código autodocumentado no significa que no 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 " auto-documentación " el código tarda más en entenderse que el código comentado, en realidad no es autodocumentado.

Otros consejos

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 qué 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 de 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 deficiente: 

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 esto en cualquier momento, 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).

El código en sí mismo 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 intención , que es la más importante. Aspecto 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 es difícil de entender.
  2) Trate de no escribir código que sea difícil de entender.

La idea detrás de " autodocumentación " El código 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. Solo por esa razón, nunca puede reemplazar el código bien comentado .

Creo que es relevante cuestionar si una línea de código en particular se auto-documenta, pero al final, si no entiendes la estructura y función de un segmento de código, la mayoría de las veces los comentarios no te ayudarán. Tomemos, por ejemplo, la porción de amdfan de " comentada correctamente " código: 

/* 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 igual de 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 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 propia experiencia personal, hay muy pocos " normales " Codificando situaciones donde absolutamente necesitas 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 opciones que llevaron al sistema a usar esas estructuras en particular.

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 puedas entenderlo al mirarlo". Solo tenemos que aceptar que no somos perfectos, pero debemos esforzarnos por ser perfectos y seguir disculpándonos cuando sea necesario.

El código de auto-documentación es un buen ejemplo de " DRY " (No te repitas). No duplique la información en los comentarios que está, o puede estar, en el propio código.

En lugar de explicar para qué se usa una variable, cambia 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 por 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 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í, cada uno de los cuales agrega un valor explicativo único sin duplicar la información en el otro.

el código de autodocumentación es una buena práctica y, si se realiza 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.

Habiendo dicho eso, los comentarios pueden ser muy útiles para los recién llegados o los probadores 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.

En primer lugar, es bueno saber que el código de su colega es, de hecho, más claro que cualquier otro código que haya visto. Significa que probablemente no esté usando " autodocumentación " como una 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 es autodocumentada: 

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 subjetivo 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 están utilizando para poder autodocumentar el código.

El mejor argumento que he visto para escribir " código de auto-documentació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 por sí solo, no puede explicar por qué algo se está haciendo de cierta manera .

En orden:

  • El código de autodocumentación es un código que expresa claramente su intención al lector.
  • No del todo. Los comentarios siempre son útiles para los comentarios sobre por qué se eligió una estrategia particular. Sin embargo, los comentarios que explican qué está haciendo una sección de código son indicativos de un código que no es suficientemente autodocumentado y podría usar alguna refactorización ..
  • Los comentarios mienten y pasan de moda El código siempre dice es más probable que diga la verdad.
  • Nunca he visto un caso en el que el qué del código no pudiera ser suficientemente claro sin comentarios; sin embargo, como dije antes, a veces es necesario / útil incluir comentarios sobre el por qué .

Es importante tener en cuenta, sin embargo, que el código de auto-documentación requiere mucha autodisciplina y disciplina de equipo. Tienes que aprender a programar de manera más declarativa, y tienes que ser muy humilde y evitar " inteligente " código a favor de un código que es tan obvio que parece que cualquiera podría haberlo escrito.

Para uno, 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í, para el 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.

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

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

Cuando realiza el mantenimiento, la información de backgorund se vuelve muy importante.

Solo mi pizca de sal ...

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

¿Has oído hablar de " WEB " de Donald Knuth? ¿Proyecto para implementar su concepto de Programación literaria ? Es más que un código auto-documentado; es más como documentación que se puede compilar y ejecutar como código. Sin embargo, no sé cuánto se usa hoy.

La diferencia es entre " lo que " y " cómo " ;.

  • Debes documentar " lo que " una rutina lo hace.
  • No debes 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.

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, ya que la persona que lo mantiene es un maníaco homocida que sabe dónde vive. "

El punto de vista de que el código se 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. Publique aquí .

el código de autodocumentación normalmente utiliza nombres de variables que coinciden exactamente con lo que está haciendo el código, por lo que es fácil entender lo que está pasando

Sin embargo, este " código de autocumentación " Nunca reemplazará a 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 haberle dicho es que " Los comentarios son para mariquitas "
Nos sorprendió a todos al principio, 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 estar 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.

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

La premisa es simple: dado que el compilador debe entender el código y los compiladores simplemente debe deshacerse de los comentarios. ¿Por qué no les da a todos lo que necesitan? Una descripción textual completa de la intención del código, sin restricciones. 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. El programa luego extrae las partes del código fuente del documento y ensambla un archivo de código.

Encontré un ejemplo en su sitio web: http://moonflare.com/code /select/select.nw o la versión HTML http://moonflare.com/ código / 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 leer it.

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

Mi opinión está escrita en esta publicación:

El único consejo para documente su código.

Extracto:

  

En lugar de escribir muchos comentarios   para explicar los comportamientos sutiles de   su programa, ¿por qué no reestructurar su   ¿Lógicas para que sean evidentes?   En lugar de documentar qué es un método.   Está haciendo, ¿por qué no elegir un nombre claro?   para ese metodo? En lugar de etiquetar   su código para indicar el trabajo sin terminar,   ¿por qué no simplemente lanzar un   NotImplementedException ()? En vez de   preocuparse de si sus comentarios suenan   lo suficientemente educado con tu jefe, tu   colegas o cualquiera que lea el código,   ¿Por qué no dejar de preocuparse por no   escribiéndolos en absoluto?

     

Cuanto más claro sea el código, más fácil será   es mantenerlo, extenderlo,   Trabajar en ello en futuras ediciones. los   menos odoroso es tu código, menos   Necesito que haya que comentarlo. Cuanto mas   Los comentarios, cuanto mayor sea el   costo de mantenimiento.

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

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

Las máquinas no necesitan código fuente. Son felices 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 se trata de escribir código.

¿Debes 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 " utilizando " en C #.

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

Los equipos no necesitan nombres de tipo, nombres de métodos y nombres de variables. 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.

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 tan fácil y claro para leer como sea posible.
  • Los comentarios deben dar razones para decisiones de diseño que tomé, como: por qué ¿Utilizo este algoritmo, o limitaciones que tiene el código, como: hace no funciona cuando ... (esto debería ser manejado en un contrato / aseveración en el código) (generalmente dentro de la función / procedimiento).
  • La documentación debe indicar el uso (Llamando Converntions), Side Efectos, posibles valores de retorno. Eso se puede extraer del código usando Herramientas como jDoc o xmlDoc. Eso por lo tanto, usualmente está fuera de función / procedimiento, pero cerca de la 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 se modifiquen cuando el código cambie, pero no se superponen en lo que expresan.

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

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

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 tu documentación, porque la documentación es lo que le das a otros para explicar cómo usar tu 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) debe 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é lo estás haciendo en ese caso;)

Al escribir código matemático, a veces me ha resultado ú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 utilicen comentarios allí.

Pero muchos códigos necesitan comentarios para que tengan sentido, así que escríbalos lo más claramente posible y luego use tantos comentarios como sea necesario ...

Argumentaría, como muchos de ustedes lo hacen, que para ser verdaderamente autodocumentados, el código debe mostrar algún tipo de intención. Pero me sorprende que nadie haya mencionado aún el BDD - Desarrollo guiado por el comportamiento . Parte de la idea es que tiene pruebas automatizadas (código) que explican la intención de su código, lo cual es muy difícil de poner de manifiesto de otra manera. 

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

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

  • El código que estás viendo se generó automáticamente, y por lo tanto, cualquier edición del código podría quedar bloqueada la próxima vez que se compile el proyecto
  • Se intercambió 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 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:

BisectionSearch

BinarySearch

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.

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, afortunadamente 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, luego 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 debe respetar a los demás miembros del equipo: si sus tareas requieren una comprensión de su código y su código no le explica todo lo que necesita comprender, necesita comentarios.

Licenciado bajo: CC-BY-SA con atribución
No afiliado a StackOverflow
scroll top