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?

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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

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

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.

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

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.

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.

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

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.

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.

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.