Tengo un colega que insiste en que su código no necesita comentarios, es «auto de documentación.»

He revisado su código, y si bien es claro que el código que he visto que otros producen, todavía no estoy de acuerdo en que la auto-documentar el código es tan completa y útil como bien comentado y documentado el código.

Que me ayude a entender su punto de vista.

  • ¿Qué es el auto documentar el código
  • Puede realmente sustituir un bien comentado y documentado el código
  • Hay situaciones donde es mejor que bien documentado y comentado código
  • Hay ejemplos donde el código no puede ser auto-documentación sin comentarios

Tal vez es sólo de mis propias limitaciones, pero no veo cómo puede ser una buena práctica.

Este no pretende ser un argumento – por favor, no traen las razones por las que bien comentado y documentado el código es de alta prioridad – hay muchos recursos que muestran esto, pero no me convencen a mi compañero. Creo que necesito entender más plenamente su perspectiva a convencer de lo contrario. Iniciar una nueva pregunta de si debe, pero no se discute aquí.

Wow, rápida respuesta! Favor de leer todas las respuestas existentes y proporcionar comentarios a las respuestas en lugar de añadir nuevas respuestas, a menos que su respuesta realmente es sustancialmente diferente de todos los otros respuesta aquí.

También, aquellos de ustedes que están argumentando en contra de la auto documentar el código -esto es principalmente para que me ayude a entender la perspectiva (es decir, aspectos positivos) de auto-documentar el código evangelistas. Espero que otros se downvote si usted no permanecer en el tema.

  • Sabes lo que realmente me impresiona? Usted no está de acuerdo con el tipo pero usted está pidiendo a entender <i>él</i>, no para obtener más munición contra él.
  • Como una historia de un extremadamente caso contrario, tengo un compañero de trabajo de quien escribe toneladas de documentación: en cada archivo cpp incluye un manual con al menos un par de docenas de páginas en la implementación y uso de las funciones previstas. Sin embargo, ella escribe desastrosamente largas y complicadas funciones (funciones individuales con 8000 líneas de código), contra-intuitivas identificadores de variables y funciones, etc. En comparación con ella, me gustaría tener a alguien tratando de escribir código auto-documentado que las holguras en los comentarios cualquier día, siempre que su código está bien organizado con pequeñas funciones que son fáciles de entender.
  • Relacionados: thedailywtf.com/Articles/…
  • En resumen, uno puede evitar la mayoría de los comentarios que explican como funciona el código y hacer que el código de auto-documentación al respecto. Pero a menudo es también necesaria para explicar porque el código funciona de la manera que lo hace, por ejemplo, cuando se trabaja alrededor de una limitación en una biblioteca. Normalmente se necesitan comentarios para explicar el por qué.
  • Yo solía trabajar con alguien que más comentado de todo, pero normalmente con comentarios inútiles, como i++; // increment i – pero con ninguna explicación acerca de por qué i debe ser incrementado en ese punto de la función.

49 Comentarios

  1. 170

    En mi opinión, cualquier código debe ser auto-documentado. En buen estado, auto-documentado código, usted no tiene que explicar cada línea única porque cada identificador (variable, método de la clase) tiene un claro semántica nombre. Tener más comentarios de lo necesario en realidad hace que sea más difícil (!) para leer el código, así que si su colega

    • escribe comentarios de documentación (Doxygen, JavaDoc, comentarios, etc.) para cada clase, los estados, el tipo y el método Y
    • claramente comentarios de ninguna de las partes del código que son no de auto-documentación Y
    • escribe un comentario para cada bloque de código que explica la intención, o qué hace el código en un nivel superior de abstracción (es decir, encontrar todos los archivos de más de 10 MB en lugar de el bucle a través de todos los archivos en un directorio, prueba si el tamaño del archivo es de más de 10 MB, rendimiento si es cierto)

    su código y la documentación está bien, en mi opinión. Tenga en cuenta que la auto-documentado que el código de no significa que no debe haber ningún comentario, pero sólo de que no habría comentarios innecesarios. La cosa es, sin embargo, que mediante la lectura de el código (incluyendo comentarios y comentarios de documentación) debe producir una comprensión inmediata de lo que el código no hace y por qué. Si la «auto-documentar el» código se toma más tiempo para entender que el código comentado, no es realmente auto-documentado.

    • En línea con esta respuesta, creo: memeagora.blogspot.com/2008/11/comments-code-smell.html
    • Punto nr. 3 debe ser parte del punto nr. 1 en mi humilde opinión, si un método es tan compleja, que requiere de un alto de abstracción de los comentarios de varios bloques de código, cada bloque de código debe ser un nuevo método.
    • +1 para el «no significa que no debe haber ningún comentario», que parece ser cierta la opinión de la gente.
    • Todavía no necesita para comentar que: public static Colección<Archivo> filesGreaterThan(ruta de acceso de Archivo, int sizeInBytes);
    • Una buena regla del pulgar para mí es que los comentarios nunca debe explicar QUÉ código se está haciendo, pero puede ser utilizado para explicar por QUÉ está haciendo. En otras palabras, el comentario de un bloque de código para explicar por qué está allí, no se cómo funciona. Si puedes factor el bloque en su propia claramente con nombre de método, entonces, que es incluso mejor. Eso es lo que la auto-documentar el código es todo acerca de.
  2. 375

    Bueno, ya que esto es acerca de los comentarios y el código, echemos un vistazo a algunos de código real. Comparar este código típico:

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

    A esta auto-documentar el código, que muestra lo que se está haciendo:

    const float gravitationalForce = 9.81;
    float timeInSeconds = 5;
    float displacement = (1 /2) * gravitationalForce * (timeInSeconds ^ 2);
    

    Y, a continuación, a este código documentado, que mejor explica por qué se está llevando a cabo:

    /* 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 parte de la documentación con cero comentarios necesarios:

    float computeDisplacement(float timeInSeconds) {
        const float gravitationalForce = 9.81;
        float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
        return displacement;
    }

    He aquí un ejemplo de un mal estilo de comentario:

    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 utiliza cuando las variables se han descriptiva con el nombre en su lugar, y los resultados de una operación se resumen cuando podemos ver claramente lo que es la operación. Prefiero el auto-documentado segundo ejemplo de esto cualquier día, y tal vez eso es lo que tu amigo está hablando cuando se dice que auto-documentado el código.

    Yo diría que depende del contexto de lo que está haciendo. Para mí, la auto-documentado código es, probablemente, suficiente en este caso, pero un comentario detallando la metodología detrás de lo que está detrás de hacer (en este ejemplo, la ecuación) es también útil.

    • Que todo el pedazo realmente debería estar en una función con un nombre descriptivo a pesar de que 😉
    • De acuerdo, pero todavía no puede poner a la ecuación matemática en el nombre del Método. Así que un comentario de ayuda, en cualquier caso
    • Sí, la función displacementDueToGravity(int: tiempoensegundos, float gravitationalAcceleration = 9.81) sería más fácil para mí para leer.
    • También, se intenta almacenar un número de punto flotante en una const int es algo tonto – se pierde una buena cantidad de precisión.
    • Sí, uy. Me fijo. Bueno yo no trabajo para la NASA…
    • El comentario echo de menos aquí es: ¿por Qué los 5 segundos?
    • Otro voto para el descriptivo nombre de la función. No le da a la ecuación en sí, pero no veo que lo que se necesita.
    • «no se puede poner la ecuación matemática en el nombre de Método» La ecuación es en el cuerpo del método, con carácter descriptivo nombres de variable en lugar de x, v, a, y t. (Por CIERTO, ¿qué pasó con v0t?)
    • ¿Cuáles son las unidades de la fuerza gravitacional? Hay límites a la cantidad que usted puede añadir un nombre de variable. En algún momento usted tiene que explicar lo que usted está tratando de hacer. A menudo esto es no es obvio, que es la razón por la que usted necesita para comentar el código. Es una absoluta basura a decir que el código es el auto de la documentación, es simplemente auto descriptivo.
    • Este <em>realmente</em> debe ser puesto en una función con un nombre descriptivo. En ese momento se convierte verdaderamente auto documentar! De hecho, cada vez que usted se encuentra escribiendo un comentario para explicar un bloque de código, que es una clara señal de que usted necesita para extraer el bloque de código en un método con el que se diga su nombre. Incluso si sólo puedes llamar a ese método una vez.
    • Sí, pero ahora mira esta perfecto ejemplo de auto-documentación: thedailywtf.com/Articles/…
    • sí, usted puede ir por la borda con la idea. Yo podría haber llamado a la primera variable «gravitationalForceInKilogramMetersoversecondssquared» Pero, en general, el principal sigue en pie.
    • Unidades! Por favor, unidades en todos los nombres de variables. timeoutSec o timeoutMs describe con precisión la variable, mientras que sólo el tiempo de espera va a ser un localizador de llamadas cuando usted tiene 1000 subprocesos en espera de 2000 segundos, no ms, para el tiempo de espera.
    • En algunos idiomas, (1 / 2), se usan los valores como enteros y terminan siendo 0, debido a los errores de truncamiento. Usted puede evitar que haciendo (1.0 / 2.0) o simplemente utilizar 0.5
    • Cierto; también, en todos los lenguajes basados en C en, que yo sepa, (b^2) no dar lo que se pretende aquí…
    • A todos lo que sugiere el uso de una función, se hace 🙂

  3. 169

    El código en sí es siempre va a ser el más up-to-fecha de explicación de lo que el código hace, pero en mi opinión es muy difícil explicar intención, que es el aspecto más importante de los comentarios. Si está escrito correctamente, ya sabemos lo lo que hace el código, sólo tenemos que saber ¿por qué en la tierra lo hace!

    • De acuerdo. Aunque de vez en cuando incluso el mejor de código puede ocultar lo que su efecto final es, esto es manejado por responder el por qué en los comentarios. Como en, «¿por Qué usted acaba de cambiar esos 5 variables de ese modo?»
    • Mis 2 centavos: no es la [Unidad, Spec, la Conducta, el ] Caso un poco una respuesta a «¿por qué en la tierra» ? A continuación, se podía leer el caso de prueba y debe ser dada la intención de por qué.
    • Creo que los que puede responder el alto nivel ¿por qué, pero no explican cosas como, «yo soy el relleno de esta estructura de este número de bytes, de manera que se quede correctamente alineado cuando se transmite a alguna oscura de la plataforma.» Para aquellos, el código de los comentarios son la mejor manera de preservar el conocimiento institucional.
    • Y por lo tanto se debe comentar donde la intención no es ambigua, dado que el código en sí.
    • su automatizada de especificaciones puede decir que a, y lo bonito que es el código que comprueba la ejecución de código. Así que si los cambios en la implementación de alguna manera, la especificación de los descansos. Qué bonito es eso? Los comentarios que le avise cuando la ejecución de código no está haciendo lo que el comentario se especifica más?
  4. 93

    Alguien dijo una vez

    1) Sólo escribir comentarios de código que es difícil de entender.

    2) Trate de no escribir código que es difícil de entender.

    • Lo que parece trivial para entender en el momento de escribir el código que en realidad puede ser muy difícil para alguien para entender más tarde, incluso si ese alguien es, de hecho, usted mismo dentro de unos meses/años.
    • A menudo me encuentro cosas que me escribió el viernes bastante difícil de asimilar en la mañana del lunes 🙂
    • lo que nos lleva a «tratar de no escribir comentarios»
  5. 36

    La idea detrás de «auto-documentación del código», es que la lógica del programa en el código es trivialmente lo suficientemente clara para explicar a cualquiera que lea el código no sólo lo que hace el código, pero ¿por qué lo está haciendo.

    En mi opinión, la idea de la verdadera auto-documentar el código es un mito. El código puede decir que la lógica detrás de lo que está sucediendo, pero no puede explicar por qué se está llevando a cabo una cierta manera, sobre todo si hay más de un camino para resolver un problema. Por esa sola razón no puede reemplazar a bien comentado código.

    • En mi humilde opinión, El bloque debe decirle la como, el nombre de la función debe decirle la porque. Mientras que el uso de ambos juntos, transmitir, tanto de la intención y la aplicación…. int GetBoundingBox() {return CalcContentDimensions() + this.padding + this.margin;}
  6. 18

    Creo que es pertinente a la cuestión de si una determinada línea de código es la auto-documentado, pero al final si no entender la estructura y función de un fragmento de código, a continuación, la mayoría del tiempo los comentarios no van a ayudar. Tomemos, por ejemplo, amdfan la rebanada de «bien-comentó el» 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 el siguiente es igualmente informativo en la mayoría de los modernos sistemas de software, y reconoce explícitamente que el uso de un Newtoniano de cálculo es una opción que puede ser alterado en caso de que algunos otros paradigma físico 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 «normal» de la codificación de las situaciones donde es absolutamente necesario disponer de comentarios. ¿Con qué frecuencia se acaban de lanzar su propio algoritmo, por ejemplo? Básicamente, todo lo demás es una cuestión de la estructuración de su sistema por lo que un programador puede comprender las estructuras en uso y de las opciones que manejaba el sistema para el uso de dichas estructuras.

    • necesita más upvotes, su ejemplo explica por qué deberíamos estar usando los nombres de función a la calidad del documento.
  7. 16

    De que se me olvide donde tengo esto, pero:

    Todos los comentarios en un programa es como una disculpa para el lector. «Yo siento que mi código es tan opaco que no se puede entender mirando». Sólo tenemos que aceptar que no somos perfectos pero se esfuerzan para ser perfecto y vaya a la derecha en pedir disculpas cuando es necesario.

    • De la basura. Muy buenos los comentarios en el código absolutamente tienen su lugar. Tomemos el ejemplo de la elección entre dos igualmente correcta de los métodos para resolver un problema. Un comentario que explique por qué uno de los métodos fue elegido por encima de los otros es sumamente significativo, y nunca se puede conseguir que desde el propio código.
    • Si hay dos IGUAL de métodos CORRECTOS, entonces no importa por qué usted eligió uno sobre el otro?
    • Sí, igualmente correcta no significa exactamente las mismas. Un método puede ser más rápido en algunas situaciones que en otro.
    • A continuación, si el criterio de decisión es la velocidad, que no son IGUALMENTE CORRECTOS. No estoy diciendo que los comentarios son malos. Sólo que son necesarios debido a que actualmente no existe un lenguaje de programación que es tan claro un inequívoco de que nadie puede mirar el código y saber de inmediato el código de la intención.
    • EBGreen: Pero lo que si desea cambiar el código? A continuación, el otro método podría tener más sentido, y esto podría explicarse, en definitiva, en los comentarios
    • No creo que la gente uderstand que cita la misma manera que lo hago. Yo esto significa que usted debe esforzarse para siempre escribir código que es tan claro que no necesita ser comentada, pero que tiene que aceptar que es un ideal que nunca funciona en la realidad.
    • Yo no creo que haya la necesidad de dos igualmente métodos correctos en cualquier situación… Ver colecciones java por ejemplo, ¿te gustaría tener 5-7 sort() métodos, cada uno de ellos IGUALMENTE CORRECTA?
    • correcto != (rendimiento || comprensible || extensible)

  8. 14

    De auto-documentación de código es un buen ejemplo de «SECO» (Don’t Repeat Yourself). No duplicar la información en los comentarios que es, o puede ser, en el propio código.

    En lugar de explicar lo que es una variable se utiliza para, cambiar el nombre de la variable.

    En lugar de explicar lo que es un corto fragmento de código, extraer en un método y darle un nombre descriptivo (tal vez una versión abreviada de su comentario de texto).

    En lugar de explicar lo que es una complicada prueba, el extracto en un método demasiado y darle un buen nombre.

    Etc.

    Después de esto termina con código que no requiere mucha explicación, se explica a sí mismo, por lo que debería eliminar los comentarios que se limitan a repetir la información en el código.

    Esto no significa que usted no tiene comentarios, hay algunos datos que no puedes poner en el código, tales como información acerca de la intención (el «por qué»). En el caso ideal, el código y los comentarios que complementan el uno al otro, cada uno añadiendo único valor explicativo, sin duplicar la información en el otro.

    • Una excepción: los malos programadores. He visto comentarios que dicen que el código está haciendo algo que no es. Entonces me pregunto: debo corregir el código o el comentario?
    • Usted no puede vencer a los nombres de método en Objective-C. 🙂
  9. 13

    de auto-documentación de código 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.

    Habiendo dicho eso, los comentarios pueden ser muy útiles para los recién llegados o para los probadores o para generar documentación/archivos de ayuda.

    de auto-documentación de código + necesaria comentarios irá una manera larga hacia ayudar a la gente a través de los equipos de.

  10. 13

    Primero de todo, es bueno saber que su colega, el código es en realidad más clara que la de otro código que has visto. Esto significa que él no es, probablemente, el uso de «auto-documentación» como una excusa para no estar demasiado perezoso para comentar su código.

    Auto-documentar el código es el código que no se requieren observaciones en texto libre para un lector informado para entender lo que se está haciendo. Por ejemplo, este fragmento de código es de auto-documentación:

    print "Hello, World!"
    

    y así es este:

    factorial n = product [1..n]
    

    y así es este:

    from BeautifulSoup import BeautifulSoup, Tag
    
    def replace_a_href_with_span(soup):
        links = soup.findAll("a")
        for link in links:
            tag = Tag(soup, "span", [("class", "looksLikeLink")])
            tag.contents = link.contents
            link.replaceWith(tag)
    

    Ahora, esta idea de un «lector informado» es muy subjetiva y situacional. Si usted o alguien más está teniendo problemas para seguir su colega del código, entonces él iba a hacer bien a re-evaluar su idea de un lector informado. Un cierto nivel de familiaridad con el lenguaje y las bibliotecas que se utilice debe ser asumido en orden a llamar a código autodocumentado.

    El mejor argumento que he visto para la escritura de «auto-documentar el código» es que se evita el problema de free-comentario de texto no estar de acuerdo con el código como está escrito. La mejor crítica es que mientras el código puede describir lo y cómo que está haciendo por sí sola, no puede explicar por qué se está haciendo algo de una determinada manera.

  11. 9

    Con el fin de:

    • Auto-documentar el código es el código que expresa claramente su intención de que el lector.
    • No en su totalidad. Los comentarios siempre son útiles para el comentario en por qué una estrategia en particular fue elegido. Sin embargo, los comentarios que explican lo una sección de código que está haciendo son indicativos de código que no es lo suficientemente auto-documentación y podría utilizar algo de refactorización..
    • Comentarios de la mentira y de la fecha. Código siempre dice es más probable que diga la verdad.
    • Nunca he visto un caso donde el lo de código no podía ser suficientemente claro, sin comentarios; sin embargo, como he dicho antes, a veces es necesario/útil incluir comentarios en el por qué.

    Es importante tener en cuenta, sin embargo, que verdaderamente auto-documentar el código tiene un montón de auto y equipo-disciplina. Tienes que aprender a programar más de forma declarativa, y usted tiene que ser muy humilde y evitar el «inteligente» de código en favor de código que es tan obvio que parece que cualquiera podría haber escrito.

    • Voy a añadir un nit recoger aquí. Código no siempre «decir la verdad». El código puede ser engañosa y ocultar sus intenciones muy fácilmente. Por ejemplo, una mal llamada variable o método puede mentir tanto como de fuera de la fecha del comentario.
    • Los nombres de método puede mentir, y puede estar fuera de fecha.
  12. 6

    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 tenemos 5 líneas de comentarios por 3 líneas de código. Peor aún, los comentarios no añadir nada que no se puede ver al leer el código. Si usted tiene 10 métodos como este, usted puede conseguir comentario ‘ceguera’ y no notar el método que se desvía del patrón.

    Si supuesto, una versión mejor 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;
     }
    

    Todavía, por trivial código prefiero no tener comentarios. La intención y la organización en general es mejor explicado en un documento aparte, fuera del código.

    • Puede parecer trivial documento getters y setters, pero creo que hay un término medio entre tener un inútil comentario y no tener ningún comentario en absoluto. El punto de un montón de comentarios de Javadoc es informar a alguien que no puede o no tiene la inclinación a mirar el código en el método.
  13. 6

    Cuando se lee un «auto-documentar el código»,
    a ver lo que está haciendo,
    pero no siempre se puede adivinar por qué se está haciendo en esa forma particular.

    Hay un montón de no-programación de restricciones
    como la lógica de negocio, la seguridad, las demandas de los usuarios, etc.

    Cuando se realiza el mantenimiento, los backgorund información a ser muy importante.

    Sólo mi pizca de sal…

  14. 5

    Una cosa que usted puede desear para señalar a su colega es que no importa cómo la auto-documentar su código es, si otros métodos alternativos fueron consideradas y descartadas que la información se perderán a menos que comenta el código con esa información. A veces es igual de importante saber que una alternativa era considerado y por qué se decidió en contra y los comentarios de código son más propensos a sobrevivir a lo largo del tiempo.

    • Toma esto como una regla y usted va a terminar de escribir el libro de texto en su código base 😉 estoy de acuerdo que no es evidente decisiones, aunque.
    • esa es una buena observación. Pero como usted dice que no evidentes las decisiones (y aquellos que normalmente son los que realmente requieren de una documentación de todos modos) es una buena práctica.
    • Documentar el código que no escrito! 🙂
  15. 5

    ¿Has oído hablar de Donald Knuth de la «WEB» proyecto para implementar su Letrado De Programación concepto? Es más que auto-documentar el código; es más como de la documentación que puede ser compilado y ejecutado como código. No sé cuánto se utiliza hoy en día aunque.

    • Este sin duda ha influido en el desarrollo de test-driven development y de comportamiento-driven development (especialmente las tecnologías como el AJUSTE y Fitnesse). Así, en una forma altamente especializada de manera práctica estándar para un montón de gente.
  16. 5

    La diferencia entre «qué» y «cómo».

    • Debe documentar «lo» hace rutina.
    • Usted no debe el documento «cómo» se hace, salvo casos especiales (por ejemplo, se refieren a un algoritmo específico de papel). Que debe ser auto-documentado.
    • Fuertemente en desacuerdo. Lo que una rutina no debería ser obvio por el nombre. Cómo no debería ser obvio a partir de la implementación del código. ¿Por qué la aplicación fue escrito como debe ser documentado.
  17. 5

    En una empresa en la que trabajaba uno de los programadores tienen los siguientes pegado a la parte superior de su monitor.

    «Documentar el código como la persona que la mantiene es un homocidal loco quien sabe de donde usted vive.»

  18. 4

    El punto de vista de que el código es auto documentando me vuelve loca. Una determinada línea de código o un sub algoritmo puede ser, en efecto, el auto de documentar, pero su propósito en el gran dibujo de problema, simplemente no lo es.

    Yo estaba tan frustrado con esto un mes o dos atrás me escribió una entrada de blog entero describiendo mi punto de vista. Post aquí.

  19. 4

    de auto-documentación de código utiliza normalmente los nombres de las variables que coinciden exactamente lo que hace el código, de modo que es fácil entender lo que está pasando en

    Sin embargo, tales «auto-documentar el código» nunca podrá reemplazar a los comentarios. A veces el código es demasiado complejo y auto-documentar el código no es suficiente, especialmente en el modo de mantenimiento.

    Una vez tuve un profesor que era un firme creyente en esta teoría
    De hecho, la mejor cosa que alguna vez me recuerde a él diciendo es que «los Comentarios son para enclenques»

    Tomó a todos por sorpresa al principio, pero tiene sentido.

    Sin embargo, la situación es que aunque usted puede ser capaz de entender lo que está pasando en el código, sino alguien que es menos experimentado que puede venir detrás de ti y no entender lo que está pasando. Esto es cuando los comentarios se vuelven importantes. Sé que muchas veces que nosotros no creemos que son importantes, pero son muy pocos los casos donde los comentarios son innecesarios.

    • A continuación, refactorizar hasta que sea más claro. Soy un firme creyente de que no hay nada que no puede ser dicho por el código de una manera bastante clara.
    • A excepción de por qué una aplicación específica, algoritmo o fórmula fue elegido por encima de otro igualmente correcta. Nunca se puede describir por qué se hizo una elección basada en el código, sólo lo que la elección fue.
    • usted podría poner ambas opciones en una clase grande y deja que el otro no implementadas con un comentario acerca de… oh wait.
  20. 4

    Estoy sorprendido de que nadie ha traído sobre «Letrado De Programación«, una técnica desarrollada en 1981 por Donald E. Knuth de TeX y «The Art of Computer Programming» de la fama.

    La premisa es simple: puesto que el código ha de ser entendido por un humano y comentarios son simplemente tirar por el compilador, ¿por qué no dar a cada uno lo que necesita – una descripción textual de la intención del código, sin trabas por el lenguaje de programación requisitos, para el lector humano y de código puro para el compilador.

    Alfabetizado herramientas de Programación de ello, dándole especial el marcado de un documento que indica las herramientas ¿qué parte debe ser de origen y de lo que es el texto. El programa de la tarde arranca el código fuente de partes del documento y se ensambla un archivo de código.

    He encontrado un ejemplo en la web de la misma: http://moonflare.com/code/select/select.nw o la versión de HTML http://moonflare.com/code/select/select.html

    Si usted puede encontrar Knuth del libro en una biblioteca (Donald E. Knuth, Letrado de Programación en la universidad de Stanford, California: Centro para el Estudio de la Lengua y de la Información, de 1992, CSLI Notas de la Conferencia, no. 27.) usted debe leer.

    Que auto-documentar el código, se completa con el razonamiento y la de todos. Incluso hace un buen documento,
    Todo lo demás es sólo bien escrito comentarios 🙂

    • Que realmente es lo contrario de la auto-documentar el código. Texto para los humanos, el código de la máquina. Y qué idioma si el código? Asamblea de curso. Los seres humanos no necesitan leer, ¿verdad? Lo único que necesitan para escribir!
  21. 4

    Mi punto de vista es escrito en este post:

    El único consejo para documentar el código.

    Extracto:

    Lugar de escribir un montón de comentarios
    para explicar las sutiles comportamientos de
    su programa, ¿por qué no la reestructuración de su
    de la lógica, de modo que ellos son evidentes?
    En lugar de documentar lo que un método
    está haciendo, ¿por qué no elegir un nombre claro
    para que el método? En lugar de etiquetar
    el código para indicar obra inconclusa,
    ¿por qué no acaba de lanzar una
    NotImplementedException()? En lugar de
    tener que preocuparse si su comentario de sonido
    educado lo suficiente a su jefe, a su
    colegas, o a cualquiera que lea el código,
    ¿por qué no acaba de dejar de preocuparse por no
    escrito todo?

    La más clara que el código es más fácil
    es de mantener, extender, a
    trabajar en ella en futuras ediciones. El
    menos ordorous es el código, el menos
    la necesidad de formular observaciones al respecto. El más
    los comentarios, la mayor de la
    mantenimiento costo.

    • Así que usted defiende nunca poner comentarios en el código y mantener en la documentación externa? Así que cuando estoy mirando en el código y tratando de entender por qué un determinado algoritmo o fórmula fue elegido en lugar de otro que tengo que dejar el código y cazar externo docs para encontrar la razón…
    • …y, a continuación, probablemente hay incluso menos garantiza que la documentación externa se mantendrá hasta la fecha cuando el cambio de código.
    • La documentación externa debe ser conciso y centrado en los principales conceptos, las decisiones críticas y listado de las áreas importantes, que podrían ser cubiertos por separado docs. Se debe leer como un ensayo y no como una lista de bulletpoints.
    • …y usted debe leer (el conjunto de las 10 páginas de la misma) antes de tocar cualquier código en el proyecto.
    • La ung, por favor, considere la posibilidad de resumir o la prestación de un extracto aquí después de que el enlace para que la gente pueda revisar su concepto básico sin necesidad de hacer clic a través.
    • La ung, he editado tu post para incluir algunos de los post enlazado. Yo también upvoted esta respuesta desde su puesto, en realidad no responde a mi pregunta.

  22. 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. Ellos están felices corriendo de la asamblea. Los lenguajes de programación son para nuestro beneficio. No queremos escribir la asamblea. Tenemos que entender lo que estamos escribiendo. La programación es acerca de la escritura de código.

    Debe ser capaz de leer lo que escribes?

    Código fuente no está escrito en el lenguaje humano. Se ha intentado (por ejemplo FORTRAN), pero no es completamente correcta.

    Código fuente no puede haber ambigüedad. Es por eso que tenemos que poner más estructura que podemos hacer con el texto. Texto sólo funciona con el contexto, lo que damos por sentado cuando utilizamos el texto. Contexto en el código fuente está siempre explisit. Creo que el «uso» en C#.

    La mayoría de los lenguajes de programación tienen redundancia, de tal forma que el compilador puede detectar nosotros cuando no son coherentes. Otros idiomas de uso más de inferencia y tratar de eliminar la redundancia.

    Tipo de nombres, los nombres de método y de los nombres de las variables no son necesarios por los equipos. Ellos son utilizados por nosotros para el posicionamiento. El compilador no entender la semántica, que es para nosotros.

    De los lenguajes de programación son un puente lingüístico entre el hombre y la máquina. Tiene que tener permisos de escritura legible para nosotros y para ellos. Secundaria demandas son que debe ser legible para nosotros. Si somos buenos en la semántica de los lugares permitidos y bueno en la estructuración del código, el código fuente debe ser fácil de leer, incluso para nosotros. El mejor código no necesita comentarios.

    Pero la complejidad que se esconde en cada proyecto, siempre tienes que decidir dónde poner la complejidad, y que los camellos para tragar. Esos son los lugares para la utilización de comentarios.

  23. 3

    Auto documentar el código es fácil optar por el problema, que con el código de tiempo, el comentario y la documentación a divergir. Y es un disciplinar factor a escribir de manera clara el código (si es que las estrictas sobre sí mismo).

    Para mí, estas son las reglas intento seguir:

    • Código debería ser tan fácil y claro
      leer como sea posible.
    • Los comentarios deben dar las razones para
      el diseño de las decisiones que tomé, como: ¿por qué
      puedo usar este algoritmo, o
      limitaciones el código, como: ¿
      no funciona cuando … (esto debe ser
      manejado en un contrato/afirmación en
      el código) (por lo general dentro de la función/procedimiento).
    • La documentación en uso de las listas de
      (llamando converntions), lado
      efectos de posibles valores de retorno. Es
      puede ser extraído de código mediante el uso de
      herramientas como jDoc o xmlDoc. Es
      por lo tanto, normalmente se encuentra fuera de la
      función/procedimiento, pero cerca de la
      el código que se describe.

    Esto significa que todos los tres medios de documentar el código viven juntos y por lo tanto son más propensos a ser cambiado cuando los cambios en el código, pero no se superponen en lo que expresan.

  24. 3

    El verdadero problema con el llamado auto-documentar el código es que se transmite lo que él realmente hace. Mientras que algunos comentarios pueden ayudar a alguien a entender el código mejor (por ejemplo, los algoritmos de pasos, etc.) es un grado redundante y dudo que iba a convencer a su interlocutor.

    Sin embargo, lo que realmente es importante en la documentación es de las cosas que no es directamente evidente desde el código: subyacente intención, suposiciones, impactos, limitaciones, etc.

    Ser capaz de determinar que un código de X a partir de una mirada rápida es la forma más fácil de ser capaz de determinar que un código no hacer Y. Él tiene para documentar Y…

    Usted podría mostrarle un ejemplo de un código que se ve bien, es obvio, pero en realidad no los cubre todas las bases de la entrada, por ejemplo, y a ver si la encuentra.

  25. 3

    Creo que la auto-documentar el código es un buen reemplazo para comentar. Si usted requiere los comentarios para explicar cómo o por qué el código es la forma en que se está, entonces usted tiene una función o los nombres de variable que debe ser modificado para que sea más explicativo. Puede ser hasta el codificador como si él va a recuperar el déficit con un comentario o cambiar el nombre de algunas variables y funciones y la refactorización del código, aunque.

    No puede realmente sustituir a la documentación, sin embargo, porque la documentación es lo que das a los demás a explicar cómo utilizar el sistema, en lugar de cómo hace las cosas.

    Edit: yo (y probablemente todos los demás) probablemente debería tener la disposición de que un Procesamiento de Señal Digital (DSP) de la aplicación debe ser muy bien comentado. Eso es principalmente porque DSP aplicaciones son esencialmente 2 bucles alimentados con las matrices de valores y agrega/multiplica/etc dijo valores… para cambiar el programa que cambie los valores en una de las matrices… necesita un par de comentarios para decir lo que están haciendo en ese caso 😉

    • Así, una función o nombre de variable proporcionará suficiente trivialmente contexto claro para explicar por qué una implementación fue elegido por encima de otro dado dos o más igualmente correcta maneras para resolver un problema?
  26. 3

    La hora de escribir código matemático, a veces me he encontrado que es útil para escribir mucho, ensayo-como comentarios, explicando las matemáticas, las convenciones de las anotaciones que el código utiliza, y cómo encaja todo. Estamos hablando de cientos de líneas de documentación, aquí.

    Yo trato de hacer mi código de auto-documentación como sea posible, pero cuando vuelvo al trabajo después de un par de meses, realmente no se necesita leer la explicación para evitar hacer un hash de ella.

    Ahora, por supuesto, este tipo de medida extrema no es necesario para la mayoría de los casos. Creo que la moraleja de la historia es: código diferente requiere diferentes cantidades de documentación. El código puede ser escrito de una manera tan clara que no necesita comentarios — para escribir lo que claramente y no utilizar los comentarios allí!

    Pero un montón de código no necesita comentarios sentido, así que escribe tan claramente como sea posible y, a continuación, utilizar tantos comentarios como sea necesario…

  27. 3

    Diría yo – como muchos de ustedes – de que para ser verdaderamente auto de la documentación, el código debe mostrar algún tipo de intención. Pero me sorprende que nadie menciona BDD aún Behavior Driven Development. Parte de la idea es que usted tiene pruebas automatizadas (código), explicando que la intención de su código, que es tan difícil de hacer evidente lo contrario.

    Buen dominio de modelado 
    + buenos nombres (variabes, métodos, clases) 
    + ejemplos de código (unidad de pruebas de casos de uso) 
    = auto documentación de software 
    
  28. 2

    Un par de razones por qué comentarios adicionales además del código podría ser más claro:

    • El código que estás mirando, se ha generado automáticamente, y por lo tanto ningún cambio en el código podría ser una paliza la próxima vez que se compila el proyecto
    • Un menos-que-aplicación sencilla fue cambiada por una ganancia de rendimiento (desenrollar un bucle, la creación de una tabla de búsqueda de un costoso de cálculo, etc).
  29. 2

    Que va a ser todo en lo que el equipo de valores en su documentación. Yo sugeriría que documentar por qué/intención en lugar de cómo es importante y esto no siempre es capturado en auto documentar el código. get/set no son evidentes -, pero de cálculo, recuperación, etc algo de el por qué debe ser expresado.

    También ser conscientes de la diferencia en su equipo si usted está viniendo de diferentes nacionalidades. Las diferencias en la dicción puede creap en la nomenclatura de los métodos:

    BisectionSearch

    BinarySearch

    BinaryChop

    Estos tres métodos contribuido de los promotores capacitados en 3 continentes diferentes de hacer lo mismo. Sólo por la lectura de los comentarios que se describe el algoritmo fuimos capaces de identificar la duplicación en nuestra biblioteca.

  30. 2

    Para mí la lectura de código que necesita comentarios es como leer un texto en el idioma que yo no lo sé. Veo declaración y no entiendo lo que hace o por qué – y tengo que mirar los comentarios. He leído una frase y tengo que mirar en el diccionario para entender lo que significa.

    Lo general es fácil de escribir código que se auto-documentos de lo que hace. A decir por qué lo hace comentarios son los más adecuados, pero incluso aquí el código puede ser mejor. Si usted entiende su sistema en cada nivel de abstracción, usted debe tratar de organizar el código como

    public Result whatYouWantToDo(){
      howYouDoItStep1();
      howYouDoItStep2();
      return resultOfWhatYouHavDone;
    }
    

    Donde el nombre del método que refleja su intención y el cuerpo del método se explica cómo alcanzar su meta.
    De todos modos no se puede decir que todo el libro en su título, para que los principales abstracciones de su sistema todavía tiene que ser documentado, así como el uso de algoritmos complejos, no trivial método de contratos y artefactos.

    Si el código que su colega de la producción es realmente auto-documentado – que suerte y a él.
    Si usted piensa que sus colegas código necesidades de los comentarios – que necesita. Simplemente abra la mayoría de los no-trivial lugar en él, leerlo una vez y ver si has entendido todo o no. Si el código es auto-documentado – entonces usted debe. Si no, pregunte a su colega una pregunta, después de que él le da una respuesta a preguntar por qué la respuesta no se ha documentado en los comentarios o código de antemano. Él puede decir que el código es auto-documento para tal persona inteligente como él, pero que de todas maneras tiene que respetar a los otros miembros del equipo – si tus tareas requieren de la comprensión de su código y su código no se explicar a usted todo lo que necesita para entender – se necesita comentarios.

  31. 2

    La mayoría de la documentación /comentarios servir a ayudar a los futuros código potenciadores /desarrolladores por lo tanto haciendo que el código sea fácil de mantener.
    Más a menudo que no terminaríamos volviendo a nuestro módulo en un momento posterior para añadir nuevas características o optimizar.
    En ese momento sería más fácil de entender el código, simplemente mediante la lectura de los comentarios que el paso a través de numerosos puntos de interrupción.
    Además prefiero pasar el tiempo pensando para la nueva lógica de descifrar el existente.

  32. 2

    //si no hay problema, no te preocupes acerca de ti.

    //Si escribir comentarios en todo, lo importante no será visto

    • Parámetro método de comentarios: Debe morir. Esta es la duplicación de código.

    //Parámetros deben ser auto-explicativo.

    • WTF-factor de imaginación: ¿alguien, incluso a mí, decir WTF esto?
    • Métodos toman en muchas veces relacionados con el negocio de datos, por lo que los datos deben ser documentados en algún lugar.
  33. 1

    Creo que lo que él podría llegar, es que si los comentarios de explicar lo que hace el código debe ser re-escrito para tener claro cuál es la intención. Eso es lo que él entiende por auto documentar el código. A menudo, esto puede significar simplemente romper largo de la función en la lógica pedazos más pequeños con el descriptivo nombre de la función.

    Eso no significa que el código no debe ser comentado. Esto significa que los comentarios deben proporcionar una razón por la que el código está escrito de la manera que es.

  34. 1

    Creo que siempre debe esforzarse para lograr la auto-documentar el código, porque se hace más fácil leer el código. Sin embargo, usted también tiene que ser pragmático acerca de las cosas.

    Por ejemplo, yo suelo añadir un comentario a cada miembro de la clase (yo uso de comentarios de documentación para esto). Esto describe lo que el miembro de que se supone que debe hacer, pero no cómo lo hace. Me parece que cuando estoy leyendo a través de código, especialmente el antiguo código, esto me ayuda a recordar rápidamente lo que el miembro de que se trata y también me resulta más fácil de leer el código y trabajando, especialmente si el flujo de código de saltos de todo un poco.

    Esto es sólo mi opinión. Yo sé de un montón de personas que trabajan sin comentarios a todos y decir que ellos encuentran que esto no sea ningún problema. Tengo, sin embargo, le pidió a alguien acerca de un método que escribieron en los seis meses anteriores y que han tenido que pensar por un par de minutos para que me diga exactamente lo que hizo. Este no es un problema si el método se comentó.

    Finalmente, hemos de recordar que los comentarios son igualmente parte del sistema como código. Como refactorizar y funcionalidad de cambio también debe actualizar sus comentarios. Este es un argumento en contra del uso de comentarios en todos, ya que son peor que inútiles si son incorrectas.

  35. 1

    Creo que es una cuestión de la cantidad correcta de la documentación, en lugar de todos o de ninguno. Si los parámetros a una función son así llamado, que a menudo no tienen para decir exactamente lo que son, por ejemplo, char *CustomerName es bastante obvio. Si utiliza valer los rangos de valores para los parámetros, usted no tiene que documentar los rangos. De la OMI, la documentación deberá cubrir todo lo que es menos evidente y, por tanto, necesita alguna explicación, y el código de la mayoría de las necesidades de documentación. Personalmente, prefiero ver un ejemplo ilustrativo de cómo una determinada función trabajos de documentación descriptiva, en la mayoría de los casos.

    Documentación para la documentación de amor puede ser una pérdida de tiempo, como la documentación de las necesidades de mantenimiento para mantenerse al día con el código base. En caso de que nadie se benefician de la lectura, no la producen.

  36. 1

    Me gustaría cambiar esta realidad.

    Pregúntate a ti mismo lo que no se entiende en su código, y entonces, le pedimos a aquellos. Y tal vez usted podría también nos dicen algunos.

  37. 1

    Esta es una excelente pregunta. Se remonta al primer lenguaje de programación que permite comentarios, estoy seguro. El código ciertamente debe ser como la auto-documentado como sea posible. Los comentarios que señalar lo obvio, debe ser eliminado. Los comentarios que hacen más fácil entender la intención, el propósito y uso de un determinado método o sección de código puede ser muy valiosa para aquellos de nosotros dolts que pueden estar menos familiarizados con el lenguaje o código en cuestión. Estructurado de comentarios que permiten la generación de la documentación de la API son un buen ejemplo. Simplemente no comentar una sentencia IF que comprueba si una casilla está marcada y me dicen que usted está comprobando para ver si la casilla de verificación está activada. La reformulación de lo obvio en un comentario es el peor de los residuos de las pulsaciones de teclado en nuestro universo.

    //For example, the above text deals with what is a useful comment
    
  38. 1

    Auto documentar el código es el código que es trivialmente fácil de entender. Nombres de variables va un largo camino para hacer que el código auto de la documentación, pero me parece que la mejor táctica es la de romper cualquier complicado lógica en diminutos pedazos pequeños y refactorizar que la información en separar los métodos con detallado e informativo nombres. Luego de su complicados métodos son simplemente una lista de pasos a realizar. La pequeña privado métodos auxiliares, a continuación, se documentan de manera suficiente por su propio nombre del método y los complicados métodos están documentados como una secuencia de resumen de los pasos a realizar. En la práctica, esta estrategia no siempre puede ser aplicado perfectamente así que los comentarios son muy útiles. Además, usted nunca debe abandonar por completo cualquier herramienta que le ayudará a escribir código que es más fácil de entender.

  39. 1

    Si el código no está completamente claro, sin comentarios, entonces hay espacio para mejorar el código.

    No estoy diciendo que «no comentar claro código». Estoy diciendo que «hacen que el código sea claro».

    Si al final se salen de su código no está claro, de alguna manera, luego utilizar los comentarios para compensar.

  40. 1

    Auto documentar el código es una tontería. Cualquiera que haya tenido que volver a visitar su código después de semanas, meses o gasp años sabe que (o días, en mi caso). (Tal vez el tipo que está promoviendo esta idea es todavía húmeda detrás de las orejas!?!?!)

    Uso significativo, los datos descriptivos nombres, factor de su código de forma inteligente, y de dejar las pistas en cuanto a por qué diablos hizo lo que hizo y va a vivir una más rica, más fullfilling vida.

    Aunque…me hizo leer una cita una vez atribuida a Bill Gates: «El código ES la documentación.»

    Vaya usted a saber.

    • No estoy de acuerdo en el «Auto documentar el código es una tontería cosa». «Uso significativo, los datos descriptivos nombres, factor de su código de forma inteligente» – Es parte de la auto documentar el código.
    • Cierto, pero ese no era mi punto, que está envuelto en la «y dejar las pistas en cuanto a por qué diablos hizo lo que hizo» comentario (sin juego de palabras).
  41. 1

    Algunas perspectivas de la no-comentar campamento.

    «bien comentada» (detallado) código es más difícil de leer y entender. Para una cosa, simplemente hay más texto a analizar. Aumenta el esfuerzo cognitivo en la comprensión de una base de Código – el no funcionales en el texto ocupa el espacio de la pantalla que podría ser utilizado para mostrar el código.

    Otro de los grandes problemas con los comentarios es que son poco confiables, especialmente en las mayores bases de código, el comentario de la pudrición de los conjuntos más rápido que lo que el bit rot.

    Y luego, por supuesto, es el esfuerzo en la escritura de comentarios. Con la excepción de la ocasional una línea clarificador, cada vez que comience a comentar código me sale uno de los dos sentimientos de culpa

    1. esta información debe ir en el conjunto de la documentación de apoyo
    2. Tengo que limpiar mi código
  42. 1

    Yo siempre uso del Sistema.para explicar lo que el código hace. De esa manera, usted puede imprimirlo y leerlo en casa :p

  43. 1

    Independientemente de puramente auto-documentación de código que se puede lograr, hay algunas cosas que vienen a la mente, uno debe hacer de todos modos:

    • Nunca tener código que es «sorprendente». Es decir. no utilice tonto macro para redefinir las cosas etc. No abusen de sobrecarga de operadores, no trate de ser inteligente en esto.
    • Split lejos de código en el punto correcto. Uso adecuado de las abstracciones. En lugar de inline con un rodillo de búfer (buffer de longitud fija, con dos punteros que se obtiene de los elementos añadidos en uno de los extremos y se retira en el otro), el uso de una abstracción con un nombre propio.
    • Mantener la función de complejidad baja. Si se pone demasiado largas o complejas, intenta dividir a cabo en otras funciones.

    Al implementar algoritmos complejos, añadir la documentación (o un enlace) en el que describe el algoritmo. Pero en este caso, tratar de ser más diligentes en la eliminación de los innecesarios complejidad y el aumento de la legibilidad, ya que es muy fácil cometer errores.

  44. 1

    Muy mezclado entradas aquí parece 🙂

    Puedo utilizar el código de Pseudo Proceso de Programación para nuevos desarrollos, que prácticamente hace que mi código auto de documentación. Empiezo a escribir Pseudo-código, sólo a la hora de escribir código nuevo, a continuación, extender sobre ella. No estoy diciendo que esta es la mejor práctica ni nada de eso, sólo estoy destacando una técnica que me parece útil si usted sabe que usted quiere una gran cantidad de documentación para el código, si se va a un tercero, el revisor, etc… que de vez en cuando también señala los problemas, para mí, antes he escrito una línea de código.

    ' check database is available
      ' if it is then allow the procedure
      ' if it isnt roll back and tidy up 
    ' move onto something else
    

    se convierte;

    ' check database is available
      if checkDBStateResult(currentDB) = Open then 
         ' if it is then allow the procedure
              proc.Ok = True 
      else
         ' if it isnt roll back
              proc.Ok = False
              CleanUp()
      end if
    
  45. 1

    Una vez trabajé con un hombre que estaba a punto de vender financiera de una suite para una gran empresa. Se insistió en que el documento el código fuente, a la que ha producido un 30+ página de la rutina de ensamblador y dijo: ‘está documentado, buscar’ – a continuación, se volcó a la página 13, y hubo un comentario ‘golpe de contador por uno’.
    Gran producto, gran creador, pero…

    De todos modos a mi mente el influyente comentarios de arriba son para establecer el contexto. Este fragmento fue declarado como la auto-documentado:

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

    Pero, yo uno de ellos, necesita un contexto para entenderlo en su totalidad.

  46. 1

    El punto de que se ha hecho comentarios debe captar la intención, pero me gustaría ir un poco más allá.

    Creo que para cualquier clase de problemas, no es un ideal (o casi) el vocabulario y la sintaxis para describirlo, y usted puede ver si usted acaba de pedir a la persona que tiene problemas para describirlos (suponiendo que la persona puede pensar con claridad).

    Si que el vocabulario y la sintaxis de mapas fácilmente (por la definición de las clases, métodos, etc.) en el código en un lenguaje de computadora, luego de que el código puede ser auto-documentado. También, la OMI, un dominio del lenguaje específico que se ha creado. (Y que es mi toscos definición de «declarativa».)

    A falta de este ideal, si el problema no se asigna directamente en el código de computadora, entonces usted necesita algo para vincular los dos juntos. De la OMI, que es el propósito de los comentarios.

    De esa manera, cuando el problema de los cambios, usted puede encontrar las partes correspondientes del código para cambiar.

    EDIT: yo no soy, por el camino, argumentando en favor de la programación orientada a objetos metodología donde cada sustantivo se convierte en una clase y todos los verbos de un método. Yo he visto bastante peyorativa construido que manera.

  47. 1

    Buen diseño de la estructura ayuda a señalar que algunas de las funciones son de uso general y para algunos de azar de la lógica de negocio a pesar de no tener un comentario diciendo «esta función es general».

    No debemos olvidarnos de diseño y documentación de especificación, aunque. Aquellos que tienen o por lo menos debe tener gran parte de los textos que no necesariamente son necesarios en los comentarios. Software a menudo tienen también los manuales de usuario y otros documentos de descripción, y que los que deben estar en sintonía con lo que hace el programa. La situación no es grande si el usuario tiene que averiguar lo que hace el software desde el código fuente en lugar de un manual. Por lo que la auto documentar el código no significa que el software ha sido documentado.

    Pensar acerca de la trazabilidad de las características, demasiado. Cuando usted tiene su manual, entonces usted debe ser capaz de rastrear las características de su código fuente y espalda para mejorar la mantenibilidad. Manuales y especificaciones no se mucho de programación, pero que son acerca de la ingeniería de software. El más grande es el software, la ingeniería es necesario.

  48. 1

    Aquí están mis mejores respuestas a sus preguntas.

    Auto documentar el código es código escrito claramente con clase, método, función, y los nombres de las variables que hacen que sea la intención y la función fácil de entender. Si se hace bien, es la documentación.

    Se puede reemplazar el código bien comentado y documentado, pero rara vez he visto. Muchas veces, los programadores creen que son lo suficientemente buenas para hacer esto, pero la mejor manera de tirar abajo es empezar a hacer preguntas. Si tienen que empezar explicando demasiado, entonces su código no era lo suficientemente clara. Usted no debería tener que leer el código para saber lo que hace.

    Puede haber algunas situaciones en las que es mejor. Si el código es simple y pequeño, entonces usted puede desorden de las cosas mediante la adición de documentación.

    Código que incluye un algoritmo debe contener comentarios. La mayoría de las veces, incluso el original programadores no pueden recordar qué diablos estaban pensando en un par de meses atrás, cuando se escribió una larga función.

  49. 0

    Auto documentado código es el código que es tan claro que un comentario que sería innecesario. Voy a dar un pequeño ejemplo:

    //iterate from 0 to 100
    for(int i=0; i < 100; i++) {
       println i
    }
    

    El comentario es bastante inútil, porque el código es claro. La documentación es una buena práctica, pero la documentación adicional que se puede agregar innecesaria de ruido para el código. Lo que su colega necesita saber es que no todo el mundo puede leer otros código y reconoce a todos los detalles.

    int calc(int a, int b) {
       return sqrt(a*a + b*b); //pythagoras theorem
    }
    

    El último fragmento de código sería más difícil de descifrar sin el comentario. Usted puede imaginar otros ejemplos que son más artificial.

    • Creo que te refieres «Pitágoras» teorema? ¿Por qué no sólo el nombre de la función que?
    • Que el primer comentario no sólo es redundante, también se puede argumentar que es malo porque no se indica el efecto secundario de que algo se está poniendo impreso – aunque este ejemplo en particular es bastante artificial.
    • El primer comentario es erróneo ya que la recorre de 0 a 99. Un destino demasiados comentarios de experiencias.
    • El segundo ejemplo debería ser algo así como «int calcHypotenuseLength(int lado1, int side2)» o «int pythagoreanHypotenuseLength(…)». Auto-documentado.
    • calcHypotenuseLength transmite el algoritmo. Esto viola ocultar información. Deje que la aplicación de seguir la pista de que, tal vez, de un método llamado vektorSum(int xVektor, int yVektor) si las propiedades matemáticas son importantes, o algo más cercano al dominio, como la distancia(int pointX, int puntiaguda)
    • en retrospectiva, calcGypotenuseLength y vekrotSum es igual en este sentido… yo estaba pensando en la de pitágoras parte…
    • De hecho, creo que este es un ejemplo de alguien que piensa que puede escribir la auto-documentar el código, pero no puede!

Dejar respuesta

Please enter your comment!
Please enter your name here