Código autodocumentado vs. Código comentado

22

Tuve una búsqueda pero no encontré lo que estaba buscando, no dude en vincularme si esta pregunta ya se ha formulado.

A principios de este mes se hizo esta publicación:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/

Básicamente, para resumir, eres un mal programador si no escribes comentarios. Mi opinión personal es que el código debe ser descriptivo y, en su mayoría, no requerir comentarios, a menos que el código no pueda autodescribirse.

En el ejemplo dado

// Get the extension off the image filename  
$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

El autor dijo que este código debería recibir un comentario, mi opinión personal es que el código debe ser una llamada a la función que sea descriptiva:

$extension = GetFileExtension($image_filename);

Sin embargo, en los comentarios alguien realmente hizo esa sugerencia:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-357130

El autor respondió diciendo que el comentarista era "una de esas personas", es decir, un mal programador.

¿Cuáles son las opiniones de todos los demás sobre el Código de autodescripción frente al Código de comentarios?

Phill
fuente
1
@ Péter: eché un vistazo a eso, pero tenía más ganas de obtener la opinión personal de las personas entre los dos, en lugar de definir los comentarios como olores de código o no.
Phill
2
Encuentro ese artículo ... horrible de leer. Muy insultante.
sevenseacat
@Karpie - Do Me hizo :(
Phill
3
"Por qué eres un mal programador de PHP" Respuesta: Porque estás programando en PHP.
Thomas Eding
Su método preferido es esencialmente usar llamadas a funciones para comentar su código. ¿Por qué no usar comentarios para eso? Las funciones deben usarse solo para código reutilizable. Personalmente odio tener que seguir el código de otra persona escrito de esta manera por la misma razón por la cual la declaración GOTO es mala: crea un código de espagueti. Los IDE modernos mejoran esto, pero no todos los lenguajes y programadores pueden usar estos IDE y todavía es desorientador. Honestamente, estoy de acuerdo en que debe comentar secciones de código que no están claras de un vistazo, solo hace que leer su código sea mucho más rápido y fácil.
dallin

Respuestas:

46

Prefiero escribir código auto documentado. Una guía para esto es Clean Code .

Esto, por supuesto, no significa que uno nunca deba usar comentarios: tienen su función, pero en mi humilde opinión, debe usarlos con cuidado. Esta respuesta anterior mía en SO explica mis pensamientos sobre el tema con más detalle.

Por supuesto, como señaló @Niphra, siempre vale la pena verificar dos veces que lo que creo que es limpio es realmente comprensible para otros. Sin embargo, esta es una cuestión de práctica también. De vuelta en la universidad, escribí piezas de código críptico simplemente debido al uso de nombres extraños y divertidos para todas las entidades de código, según mi capricho. Hasta que mi maestro rechazó una de mis tareas, señalando amablemente que no podía averiguar qué módulo era el principal :-) Esa fue una buena lección, así que me esforcé por centrarme en escribir código cada vez más legible desde entonces. Hoy en día apenas recibo quejas de los compañeros de equipo.

Péter Török
fuente
Me encanta ese libro :)
Phill
Todavía encuentro comentarios valiosos para expresar la estrategia utilizada, y aquellos que fueron rechazados (con la razón). Estoy de acuerdo en que los micro comentarios generalmente son inútiles.
Matthieu M.
99
Una de mis citas favoritas de Clean Code es que cada comentario es una falla para expresarse en código.
Doval
66
@Doval: una filosofía interesante, al menos con respecto a los comentarios sobre lo que hace el código . Por otro lado, algunos de los comentarios más útiles pueden ser aquellos sobre por qué el código no hace algo, un concepto que no creo que deba esperarse que exprese el código.
supercat
1
No estoy de acuerdo por completo. Ninguna cantidad de nombres va a describir completamente el propósito de la lógica.
Kolob Canyon
65

No debe documentar lo que está haciendo el código, pero debe documentar por qué lo está haciendo.

Ninguna cantidad de trucos de nombres expondrá los por qué y por qué, por lo que debe agregar comentarios para explicar el propósito de los diversos bits de código.

Todos los otros comentarios se pueden eliminar de forma segura.

biziclop
fuente
3
+1 El ejemplo en el artículo vinculado dice "hacer comentarios en cualquier situación en la que el propósito del código que he escrito no sea evidente de inmediato". - Es una tontería creer que el código por sí solo puede comunicar un propósito , porque las máquinas en sí mismas no tienen un concepto de propósito. Ejemplo contrario: tenemos errores en casi todo el software que se haya escrito, esto es una verdad. Si una computadora entendiera el propósito (el por qué ), simplemente se negaría a hacer algo más que lo que pretendíamos, en lugar de recrear debidamente el qué / cuándo / cómo / dónde eso condujo al error.
David Meister
Todo el código dentro de una función debe estar allí para cumplir el propósito de la función, es decir, lo que hace, por ejemplo, escribir algo de texto en un archivo, la función "writeTo (String text, File file)". Si algún código tiene un propósito diferente, por ejemplo, verifique las condiciones previas, como verificar que el archivo existe Y NO es evidente, entonces quizás una mejor idea que un comentario es escribir una nueva función, por ejemplo, "checkWritable (archivo de archivo)". La calidad del código no es una lista de verificación dogmática, pero si necesita comentarios, es una mala señal, y los "por qué" no son una buena razón para necesitarlos . ¿ Por qué el pollo cruzó la calle?
Trylks
2
@ Trylks Eso funciona para algunos casos pero no para todos. Imagínese este escenario: for (int i = 0; i < length/2;i++) { //if length is odd, the middle element should stay in place. Ahora, esto no es algo que sea obvio por el propósito de la función de cierre, ni podría ser factorizado en su propia función. Si lo dejas sin comentar, eso es claramente malo. Entonces agrega un comentario para aclarar su intención.
biziclop
2
@ Trylks Además, incluso si tomamos tu ejemplo, factorizas tu pago en un método y lo llamas, genial. Ahora todo lo que tiene que explicar es por qué necesita verificar que el archivo sea editable. :)
biziclop
38

En realidad no creo en el código de autodescripción. Hay un código más legible y menos legible , según el idioma, su conocimiento del mismo (como autor original), el conocimiento del tipo que lo lee y la función del código. Pero no, aún así ... debería describirse con un breve comentario.

Lo que está claro para mí ahora, que estoy en esa área de pensamiento , probablemente no lo esté para mí en un año, cuando estoy pensando en algo completamente diferente y necesito usar esta parte del código nuevamente.

Entonces, comente su código. Por supuesto, no todas las líneas (cielos, no), pero coloque algunas líneas de comentarios sobre una función / subrutina / módulo , o una parte particularmente complicada y diga en breve lo que hace. Te lo agradecerás en uno o dos años.

Torre
fuente
He estado allí, hecho eso. El "código menos legible" debería mejorarse en un código que se lea bien. El conocimiento de un idioma realmente no cuenta: cuando no esté familiarizado con la sintaxis, primero debe aprenderlo; francamente, esa es la base para ser un profesional. Intentar compensar un código terrible agregando comentarios no es una buena idea. Los comentarios nunca deberían intentar describir lo que hace el código. Un comentario (general) se justifica solo si necesita decir el por qué y no el qué . Todo lo demás es solo ruido y cosas adicionales innecesarias para mantener.
Powerslave
PD: Sé que estoy 'zombie' :) Lo siento por eso
Powerslave
Para evitar confusiones, estoy hablando del caso habitual, cuando los requisitos comerciales no lo obligan a escribir código incorrecto (por ejemplo, rendimiento excepcional o ajuste en almacenamiento confinado). En otros casos (raros), no tiene más opción que dejar comentarios, lo que alivia un poco la carga de la próxima víctima.
Powerslave
19

Afortunadamente, ambos campos en esta discusión están representados aquí, y se mencionaron argumentos a favor y en contra de ambos.

Creo que ambos campos tienen argumentos superpuestos, y en realidad están de acuerdo con la mayoría de ellos, la forma en que lograrlos es un poco diferente.

Argumentos superpuestos

  • El código debe ser legible.
  • Los comentarios no deben decir exactamente lo mismo que dice el código, pero dan más información cuando es necesario.
  • Todos los nombres de variables / funciones deben pensarse bien para que den una buena representación de lo que son / hacen.
  • Se debe evitar el código duplicado.

Ahora, la principal diferencia es cuánto peso se le da a algunos de esos argumentos.

Código autodescriptivo

  • Los comentarios pueden volverse obsoletos, así que minimice su uso, ya que los comentarios incorrectos son peores que ningún comentario.
  • Los comentarios son una duplicación del código. Todo lo que puede escribirse en código, debe escribirse en código.

Más comentarios

  • Los comentarios son más legibles que el código. El inglés simple es mejor para describir algo.

  • El código simple a menudo causa ambigüedad que debe ser comentada de todos modos. Tratar de describir esto en código da como resultado nombres demasiado largos. Además, te enfrentas constantemente con esta información 'extra' que solo necesitas la primera vez que la encuentras.

Creo que ambos campos tienen argumentos muy válidos, pero no deberías seguir frenéticamente un campamento, solo porque resuelve un problema.

Para demostrar, en el libro Clean Code , el código se divide en numerosos métodos más pequeños que solo se llaman una vez. Los métodos se crean por la única razón de documentar el código (y TDD más fácil). Esto resulta en la función del infierno . El código es menos legible de lo que era originalmente, y mientras se refactoriza, no se pensó en encapsular el código reutilizable.

Por otro lado, a menudo se ven API's donde se comentan todas las funciones, solo porque 'los comentarios son buenos'. Las cosas que deberían haber sido comentadas todavía no lo son.

Steven Jeuris
fuente
1
@Steven - "Por otro lado, a menudo se ven API en las que se comentan todas las funciones, solo porque 'los comentarios son buenos'. Las cosas que deberían haber sido comentadas todavía no lo son". ¡Uf, tan frustrantemente cierto!
dss539
Esta es una muy buena respuesta! Una cosa, si no le importa, sobre la legibilidad de los comentarios: personalmente no creo que los comentarios sean más legibles. Nosotros, como desarrolladores, usualmente pensamos en el código fuente, especialmente cuando estamos en "modo de codificación". En esos momentos, la vaguedad del lenguaje humano simple suele ser más una distracción que una ayuda.
Powerslave
5

"Lo siento pero eres ese tipo".

Me pregunto por qué no le gusta comentar: P

En serio, la codificación es demasiado de un arte que realmente podría hacer una declaración tan amplia. A veces necesitas comentarios, a veces más y mejores funciones con nombre. Usualmente ambos.

Busque la programación alfabetizada como un estilo extremo.

vegai
fuente
Sí. Quiero decir, si Donald Knuth piensa que no solo necesitas comentarios, sino que a veces necesitas capítulos de ellos, lo pensaría al menos dos veces antes de estar en desacuerdo.
PeterAllenWebb
3

La respuesta corta, mejor y correcta

La idea de que un "código auto documentado" bien escrito es todo lo que necesita es un antipatrón y debe morir, incluso cuando se hacen excepciones para comentarios que explican "por qué". Es un mito que siempre puede escribir todo el código para cualquier algoritmo lo suficientemente claro como para que cualquier programador lo mire y lo obtenga (o que no requerirá refactorización o tiempo organizativo que no tenga). Aún más importante, la mayoría de las veces, los programadores que piensan que escriben código claro no lo hacen.

Una respuesta mucho mejor que los comentarios solo debe usarse para explicar "por qué" es que los comentarios deberían:

  • explicar "por qué" (por supuesto)
  • explique "qué" en líneas individuales solo cuando el código es complejo o el propósito no está claro y no puede ser o no vale la pena simplificar aún más
  • explicar "qué" para los bloques de código para acelerar la comprensión y localizar lo que necesita

La explicación para respaldarlo

Las personas piensan erróneamente que la única razón por la que las personas usan los comentarios es para explicar lo que significa una línea de código. La verdad es que un gran propósito de comentar código es hacerlo más rápidoechar un vistazo a tu código y encontrar lo que estás buscando. Cuando vuelva a codificar más tarde o lea el código de otra persona, claro, puedo leer y comprender una sección de código bien escrito, pero ¿no es más rápido y fácil leer el comentario en la parte superior que dice qué hace esa sección de código y omitirlo por completo si no es lo que estoy buscando? ¿Por qué sentarse y descifrar el código, incluso si está bien escrito, si puede mirar un par de comentarios y comprender una función completa? Es por eso que usamos nombres descriptivos para las funciones: nadie dice que no necesito usar un nombre descriptivo para mi función porque alguien puede mirar mi código escrito para ver qué hace.

Por ejemplo, si estoy revisando la función de otra persona, ¿es más fácil ir línea por línea a través del código para ver qué está haciendo o mirar tres comentarios bien escritos en toda la función para ver exactamente qué está haciendo la función y dónde lo esta haciendo?

Otro antipatrón es el uso excesivo de funciones para comentar su código. Las funciones bien nombradas son una parte importante de la documentación del código, pero a veces los programadores separan 2-3 líneas de código que nunca se utilizarán en ningún otro lugar en una función con fines de documentación. ¿Por qué el uso excesivo de funciones es mejor que el uso excesivo de comentarios? Usar funciones como esa es lo mismo que adoptar declaraciones GOTO: crea un código de espagueti que puede ser difícil de seguir.

Esencialmente, cuando trabaja en un entorno empresarial, donde las personas comparten código constantemente y las personas no siempre tienen el tiempo para perfeccionar su código, algunos buenos comentarios pueden ahorrarle mucho tiempo y frustración. Y recuerde, si bien puede ser un gurú que puede leer el código a la velocidad de la luz, probablemente no todos en su oficina lo sean.

dallin
fuente
Odio cuando la gente rechaza y ni siquiera deja un comentario por qué. ¿Leíste toda la publicación? ¿Qué hay allí no es directo y verdadero? ¿Con qué no estás de acuerdo? Siento que las personas están tan concentradas en su idea o en lo que leen que ni siquiera piensan en ello y rechazan cualquier cosa inmediatamente que no comparta su punto de vista.
dallin
3
Supongo que es porque rechazas y nombras un antipatrón que es casi universalmente reconocido como correcto. Ciertamente creo que vas demasiado lejos. Sobre todo, no puedo imaginar comentarios de confianza tan bien como parece. Si lees a ciegas los comentarios y no el código, los comentarios pueden estar equivocados y desactualizados, y nunca lo sabrías. Esa es la base del uso de funciones como documentación. Estoy de acuerdo en que no debería tener demasiadas funciones en un solo lugar, aunque la solución a esto definitivamente no es reemplazarlas con comentarios.
Magus
@ Magus Gracias por el comentario. Supongo que se refería a mi forma de hablar sobre el uso de funciones como documentación. Al releer eso, creo que lo redacté mal para sonar como si quisiera decir que usar funciones para ese propósito en absoluto (en oposición al uso excesivo de funciones para ese propósito) fue malo. He limpiado ese párrafo para aclarar mi intención original. Mi opinión acerca de confiar en los comentarios es que si un comentario se vuelve obsoleto, generalmente es una señal de que estaba comentando una sección de código demasiado estrecha: que estaba comentando la implementación en lugar de la intención.
dallin
but isn't it faster and easier to read the comment at the top saying what that section of code does and skip it altogether if it's not what I'm looking forSe llama "el nombre del método / función". Si tiene un bloque de código que no tiene nombre pero es tan largo que no puede asimilarlo con una simple mirada, tal vez el problema esté ahí.
biziclop
1
@biziclop Tiempo extra Llegué a creer que este argumento es principalmente semántico, y en la práctica, nuestro código sería similar. Dicho esto, suponiendo que el bloque de código no se use en más de un lugar, no veo una diferencia entre un bloque de código con un breve comentario descriptivo en la parte superior y un bloque de código con un breve nombre descriptivo de la función en el parte superior. Son lo mismo, excepto que uno no tiene espacios. Ambos pueden estar equivocados y desactualizados. La única diferencia que realmente veo es que el código es más fácil de leer con un comentario, ya que no tiene que seguir la llamada de función a una ubicación separada.
dallin
2

Bueno, también tienes que recordar algo que es obvio o "autodocumentado" para ti, puede que no sea para otra persona ... Tal vez alguien con menos comprensión de ciertas funciones. Así que comento casi todo.

usuario6791
fuente
1
Puede dar un ejemplo. Quiero decir dado el ejemplo en mi pregunta original. "GetFileExtension" ¿cuál es el punto en el comentario "Obtiene la extensión de archivo de un archivo determinado"? El método ya ha descrito lo que debe incluirse en el comentario. Si el método se denominó "GetExtension", un comentario ayudaría a aclarar qué debe hacer el método, ya que el método no se explica a sí mismo.
Phill
+1 Esta es una pregunta para conocer a tu audiencia. ¿Quién es probable que use esta función? Como puedes ayudarlos? ¿Cuánto valdrá tu ayuda? ¿Vale más que pasar un poco de tiempo ahora para agregar un comentario? Etc. Etc. Etc.
PeterAllenWebb
2
@PeterAllenWebb: No tiene sentido ese comentario en absoluto. Eso no significa remotamente que la función no deba ser comentada; debería. ¿La "extensión" incluye el punto o no? ¿Para qué sirve el valor de retorno "foo"? ( null?? "") Para "foo."? ¿Pasar nullprovocará una excepción, o la función devolverá algo (tal vez null)?
TJ Crowder
2

Bueno, el código autodocumentado es que dentro de esa función, encontrarás:

$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

lo cual se explica por sí solo cuando tienes el nombre de la función, ya que solo son dos líneas. Cuando las cosas se vuelven más complicadas, debe ajustar cada pocas líneas de código en una función con un nombre descriptivo, o usar comentarios cuando sea necesario .

Nunca entendí por qué debería ser una o una cuestión, en lugar de y / y. Sí, haga que su código sea tan autodocumentable como sea posible, y sí, agregue algunos comentarios a las partes que, de lo contrario, serían poco claros.

Joris Meys
fuente
Sí. Creo que tienes que estar "entrenado" para pensar que debería ser uno u otro y no ambos.
PeterAllenWebb
2

Los comentarios y el código limpio auto documentado son diferentes. El código se trata de cómo hacer las cosas. Y los comentarios deben cubrir la parte del por qué , que no puede explicarse en código, sea cual sea su idioma. Además, si su idioma es muy limitado y no tiene contratos, no hay especificaciones estáticas e incluso ninguna afirmación, los comentarios deben cubrir los problemas de límites de su código.

SK-logic
fuente
Suponiendo que hay una razón para todo, ¿debería comentarse?
JeffO
Sí, precisamente Es por eso que creo que la mejor manera de comentar su código es una programación alfabetizada.
SK-logic
1

En ese caso, es fácil hacer una función descriptiva. Pero he leído mucho código hecho por buenos programadores que creían que su código era autodocumentado, y lo que había sido claro para ellos fue realmente confuso para mí.

$ extension = GetFileExtension ($ image_name);

Para volver a su ejemplo, ¿puedo enviarle una matriz de nombres de imágenes o solo toma una imagen? ¿Admite algún tipo de archivo, o solo algunos de ellos? ¿Asegurará la cuerda por mí o tengo que hacerlo? Si el tipo de archivo no existe, ¿me lo notifica?

Por supuesto, estoy estirando esto un poco. Pero recuerdo un programador que creía que audio_bandwidth y video_bandwidth eran nombres autodocumentados; resultó que el audio tenía que expresarse en bytes y el video en kilobytes. Tomó mucho tiempo resolver eso.

revs Niphra
fuente
55
Lo estás estirando mucho. La función obtiene la extensión del nombre del archivo. Nada más y nada menos. Su nombre dice si toma una matriz o no (claramente no). No puedo pensar en un método que dependa del tipo de archivo para obtener la extensión. Asegurar la cadena es la única que se puede incorporar, pero nunca lo esperaría porque, como sabe cualquier desarrollador de PHP: toda la información del usuario es sospechosa, así que asegúrela antes de usarla.
Matt Ellen
2
@Matt: El "claramente no" es una indicación de que no se hace mantenimiento muy a menudo. Ser explícito ahorra mucho rascarse la cabeza (y RTFSource) más adelante, y también documenta lo que el autor original esperaba que hiciera. Ya sea que esté en un comentario o en un nombre de función largo no es tan importante.
Donal Fellows
Tal vez el ejemplo fue malo para usar en esta pregunta, no he tocado PHP en aproximadamente 7 años, he estado haciendo C # y un poco de Java, así que estoy acostumbrado a tener un IDE que me indica el tipo devuelto o declarando los tipos.
Phill
1
@Donal Fellows: dice archivo, singular. ¿Qué tiene de ambiguo eso? Es completamente explícito.
Matt Ellen
44
El hecho de que ahora hay 7 respuestas de 4 personas que discuten la obviedad o no de una sola llamada de función me sugiere que necesita usar comentarios . También se destacó el hecho de que la denominación precisa es una forma de arte en sí misma.
Ant
1

Uno no excluye al otro. A pesar de que su código se comenta por sí mismo, hay ocasiones en las que puede necesitar comentarios regulares para explicar por qué su código hace lo que hace.

gablin
fuente
Creo que esto cae en mi opinión, que era "el código debe ser descriptivo y, en su mayoría, no requerir comentarios, a menos que el código no pueda autodescribirse". Si escribe código que está bien escrito, no explica completamente la intención del código, entonces los comentarios ayudan a hacer que el código sea más descriptivo.
Phill
El código nunca puede explicar su propósito. Cuando ves un martillo, no puedes entender para qué sirve, es para romper cráneos o simplemente para forjar un hierro en bruto.
SK-logic
1
@ SK-logic:public <T> void hit(T item);
Michael K
@ Michael - exactamente. ¿Cómo descubrirá el usuario, qué categorías de objetos pueden y deben ser martillados? Incluso con un sistema de tipos mucho mejor, no siempre está claro, qué rango de usos posibles está realmente planificado por un desarrollador.
SK-logic
1

No estoy de acuerdo con ese artículo y estoy de acuerdo contigo hasta cierto punto. Si usa buenos nombres de métodos, buenos nombres de variables y métodos pequeños que hacen una sola cosa, el código debe ser simple de seguir.

Solo trata de no ser inteligente porque el código inteligente es horrible de leer y mantener. Palabra clave: mantener !

Mi opinión es que los comentarios deben describir el por qué y no el qué. Recuerde que en este mundo hipotético perfecto, su código es lo suficientemente limpio como para permitir una lectura fácil, no necesita explicar lo que está haciendo, sino por qué eligió hacerlo de una manera u otra.

Si está utilizando un sistema de control de fuente, puede utilizar el mensaje de confirmación para que todos (y usted) sepan lo que hizo en un momento dado y, lo que es más importante, por qué.

Sergio
fuente
1

Desea evitar escribir comentarios al igual que evitar cualquier documentación. Cuando se trata del lenguaje de programación en sí, todos operan desde el mismo conjunto de vocabulario y sintaxis (casi).

Cuando su aplicación es para un dominio en particular, puede ser difícil lograr que todos participen para acordar y / o establecer un vocabulario común. Nos enseñan a evitar abreviaturas y jerga extensa, pero voy a llamarlo

EBITDA

y no

EquidadAntesInterés de interésImpuestosDepreciaciónYAmortización

Si no conoce uno, probablemente no entienda el otro. Si la compañía tiene una implementación poco común, un comentario ayudaría al próximo programador que tenga experiencia en el dominio, pero no a esta firma en particular (lo que hace las cosas más complicadas).

JeffO
fuente
1

Creo que debemos distinguir entre la documentación y la expresividad del código.

Al depurar o revisar el código, no estás leyendo un libro. La mayoría de las veces solo desea saltar de un método a otro y hacer conexiones rápidas en su mente para obtener una comprensión básica de lo que sucede en el tiempo de ejecución. No es la documentación alrededor del código sino la expresividad de las firmas del código lo que importa en ese proceso, su capacidad de ser lo suficientemente significativa como para que pueda identificarlos de inmediato y agregarlos a su propia pila de llamadas internas. En ese punto, nuestro cerebro (al menos el mío funciona de esa manera;)) tiende a considerar los grandes bloques de comentarios como un ruido en lugar de una ayuda. Por lo tanto, los comentarios de una línea, o incluso mejor, solo el método autodescriptivo y los nombres de objetos son suficientes aquí.

Si desea "leer el libro" de una clase o característica en particular, un lugar mucho mejor para eso es en las pruebas unitarias. Las pruebas unitarias bien diseñadas son, por naturaleza, reveladoras de intenciones y mucho más documentadoras (es decir, explicativas, detalladas) que los bloques de comentarios más gruesos, ya que contienen 1 / las expectativas sobre exactamente lo que se supone que debe hacer este código y 2 / la capacidad de verificar Estas expectativas contra el código real. Una prueba de aprobación es cien veces más confiable que cualquier comentario en términos de documentación, porque demuestra que lo que afirma es cierto.

guillaume31
fuente
1

Algunos códigos simplemente no están auto documentados, y requieren algunos comentarios de un compañero humano que entendió y probó esa pieza. Lo que tengo a continuación no es suficiente para entenderlo, creo.

//
// iterative version
//
Node* ReverseList( Node ** List ) 
{

  Node *temp1 = *List;
  Node * temp2 = NULL;
  Node * temp3 = NULL;

  while ( temp1 )
  {
    *List = temp1; //set the head to last node 
    temp2= temp1->pNext; // save the next ptr in temp2
    temp1->pNext = temp3; // change next to privous
    temp3 = temp1;
    temp1 = temp2;
  }

  return *List;
}
Trabajo
fuente
1

En general, prefiero escribir código autodocumentado, con comentarios donde no está claro, ya que creo que la mayoría del código no se documentará por completo.

Abbafei
fuente
0

En la universidad, nos enseñaron a reformular prácticamente todas las líneas de código en inglés con un comentario (probablemente solo para acostumbrarnos a comprender lo que realmente hace el código, en lugar de simplemente copiar / pegar algo y esperar lo mejor).

Personalmente, creo que eso desordena tu código, haciéndolo menos legible que si solo fueran comentarios o solo código. Soy un codificador de C # y los únicos comentarios que hago todo el tiempo son los bloques de comentarios de "triple barra" que se interpretan de nuevo en la documentación de IntelliSense. Si me siento especialmente culpable por una forma particular de hacer algo, o si parece especialmente críptico, daré una explicación más detallada, pero eso es todo.

OMI: El código autodocumentado es un código donde los nombres de variables y métodos reciben nombres significativos y contextuales, de modo que describen cuál es su propósito.

James Love
fuente
0

Si ha revisado su código varias veces y aún no ha encontrado una manera de dejar en claro la intención de alguien que conozca el dominio. Reescribe la función. Después de todo, no son más de 10-20 líneas. Si es más largo, reescriba la función de todos modos, es demasiado larga y eso es parte de por qué es ilegible :) enjuague-repita

y en el improbable caso, aún no está claro qué está haciendo el código y ha recordado pedir ayuda a sus compañeros. Bueno, entonces todos te agradecemos por ayudar a la evolución de Linux porque es el código del núcleo lo que estás escribiendo, ¿verdad? si no, enjuague, repita desde arriba :)

Simplemente no escribas tus comentarios CÓDIGOS

Runa FS
fuente
0

Echa un vistazo a Code Complete 2nd edition, pg 128-129.

Los tipos de datos abstractos lo salvarán de este enigma. El código autodocumentado es el camino a seguir. Los comentarios pueden ser útiles, pero tener

entidades del mundo real en lugar de implementaciones de bajo nivel

puedes evitar usar comentarios.

Una cosa sobre los comentarios es que los escribe una vez, pero no los ve cuando implementa la función, solo los ve cuando cambia la función.

Los comentarios son realmente útiles cuando el IDE los interpreta de la manera en que funciona Delphi 2009+ o JavaDoc, pero es más un lenguaje de marcado estructurado, por lo que, en cierto sentido, está programando su documentación, que es muy inteligente.

Peter Turner
fuente
0

Creo en el mantra de que el código no se documenta a sí mismo, porque podrías ser el mejor programador del mundo (Ada) y, sin embargo, no entiendes nada de lo que está sucediendo, pero si documentas por qué y en breve cómo su código está haciendo lo que hace, se va a ayudar a sí mismo y a los demás en el futuro.

Coyote21
fuente
0

Los comentarios son imprescindibles. Porque cuando escribes código, estás escribiendo para tus necesidades actuales, pero también para las personas en el futuro que tienen que leer tu código, averiguar qué haces, y por qué, y luego cómo hacer modificaciones para ello.

Si solo tiene esto en cuenta, ¿cuándo codifica / programa?

¿Cómo puedo hacer que esto sea más fácil de entender y modificar para los futuros codificadores de este código en el que estoy trabajando? Entonces harás un buen trabajo. De lo contrario, solo está dificultando que otros modifiquen su código, y no imagine que nunca será el caso, eso es raro ...

En la mayoría de mis trabajos, siempre tuve que modificar el código de otras personas, y lo más horrible fue escrito, mal documentado.

Entonces, su hábito de pensar que el documento de código es propio, simplemente no es hacer la debida diligencia.

Como programadores, debemos practicar la autodisciplina que puede parecer totalmente ar para los programadores sin experiencia, pero debe tener hábitos, para evitar todas las experiencias horribles que hemos tenido con el código de otras personas. O incluso mirando nuestro propio código meses, años después.

Echa un vistazo a http://thedailywtf.com , tienen toneladas de historias humorísticas pero reales sobre programadores que simplemente no hicieron su debida diligencia.

crosenblum
fuente