¿Cómo puedo tratar con un miembro del equipo al que no le gusta hacer comentarios en código?

184

Uno de los miembros de mi equipo siempre evita hacer comentarios en su código.

Su código no se documenta por sí mismo, y otros programadores tienen dificultades para comprender su código.

Le he pedido varias veces que comente su código, sin embargo, solo da excusas o afirma que lo hará más tarde. Su preocupación es que agregar comentarios tomará demasiado tiempo y retrasará los proyectos.

¿Qué argumento puedo presentarle para convencerlo de que documente correctamente su código?

En ese sentido, ¿me equivoco al centrarme en los comentarios del código o esto es indicativo de un problema mayor que debería abordarse?

Mahbubur R Aaman
fuente
109
Comentar por comentarios no mejora el código. Si el código es comprensible (incluido el por qué) sin comentarios, está bien, de lo contrario, comente.
Martin York
63
Ah, sí, y cuando la complejidad de una pieza de código se triplique para resolver una condición de carrera o un punto muerto, ¡no hagas ningún comentario al respecto! Deje que las personas resuelvan el enigma de por qué el código debe ser como es, y por qué se rompe de manera misteriosa si hacen cambios experimentales. Todos deberían ser un gran maestro del ajedrez de la concurrencia ...
Kaz
12
@Kaz Sarcasm (espero) no se traduce bien al texto.
deworde
10
@deworde & artjom: sí, eso es sarcasmo. no, no parece tan limpio como podría, pero es claramente sarcasmo.
17
siguiendo el principio de Dale Carnegie, debes tratar de entender por qué no quiere comentar ... mencionaste que no quiere retrasar el proyecto ... así que puedes decirle que si él no comenta, el de otros no sería capaz de entender el código y eso retrasaría aún más el proyecto ... esto definitivamente debería ayudar ...
Anirudha

Respuestas:

431

Los comentarios por sí solos no hacen un mejor código, y solo presionar por "más comentarios" probablemente le dará poco más que /* increment i by 1 */comentarios de estilo.

Así que pregúntate por qué quieres esos comentarios. "Es la mejor práctica" no cuenta como argumento a menos que comprenda por qué.

Ahora, la razón más llamativa para usar comentarios es para que el código sea más fácil de entender, y cuando las personas se quejan de la falta de comentarios, son loros despistados o les cuesta entender el código con el que están trabajando.

Por lo tanto, no se queje de comentarios faltantes: quejarse de código ilegible. O mejor aún, no te quejes, solo sigue haciendo preguntas sobre el código. Para cualquier cosa que no entiendas, pregúntale a la persona que lo escribió. Deberías estar haciendo eso de todos modos; con código ilegible, solo hará más preguntas. Y si regresa a un código más tarde, y no está seguro de recordar correctamente lo que hace, vuelva a hacer la misma pregunta.

Si los comentarios pueden solucionarlo, y su colega tiene un cerebro funcional, en algún momento se dará cuenta de que comentar el código es mucho más fácil que tenerlo haciendo preguntas estúpidas todo el tiempo. Y si no puede hacer preguntas, entonces tal vez ese código ya sea perfectamente legible, y es usted quien tiene la culpa; después de todo, no todo el código necesita comentarios.

En el frente de las habilidades de las personas, evite sonar condescendiente o acusador a toda costa; Sea serio y honesto acerca de sus preguntas.

tdammers
fuente
269
+1 para "no se queje de comentarios faltantes: quejarse de código ilegible".
Md Mahbubur Rahman
44
¿Qué sucede si la respuesta a cualquier pregunta sobre el código está en la línea de "¿Qué has hecho para entenderlo?"
Saul
40
+1: presionar para obtener nombres de funciones legibles puede tener beneficios adicionales ... En Revisión de código: "No puedo entender lo que está haciendo xg_jkhsfkasq". "Oh, está vaciando el búfer de alimentación principal, ¿puedo liberar ahora?" "Claro, pero dudo en aprobarlo hasta que haya cambiado el nombre de la función flush_primary_buffer" "Ah, pero también está borrando el caché principal, por lo que ese nombre sería engañoso" "¿QUÉ ES? No borre ese caché, es ¡Haré que el sistema se detenga! Mientras está cambiando esa lógica, ¿le importaría cambiar el nombre de esa función? "
deworde
18
Me preocuparía dar la impresión de que no puedo leer el código. Un gerente no técnico podría notar que constantemente le pido ayuda a 'Bob' porque el código de Bob es demasiado avanzado para mí. Eso significaría que Bob es un desarrollador 'avanzado' y no estoy listo para trabajar a su nivel.
Rob P.
55
@ Rob P. Veo el miedo, pero si no puedes leer el código y se espera que mantengas el código, entonces el código no está bien escrito o no sabes lo suficiente. Si no sabe lo suficiente, debe preguntar. Si preguntar revela que el código es simplemente difícil de leer, presione para que se solucione. El truco sería, si va por la ruta de la ingeniería social, mezclarlo si Bob va a su escritorio o usted va al suyo, y ser muy activo al señalar las cosas. Después de todo, un gerente no tecnológico no será capaz de comprender el contenido de la discusión ...
deworde
114

He conocido a muchos desarrolladores que tuvieron problemas para escribir código autodocumentado o comentarios útiles. Este tipo de personas a menudo carecen de suficiente autodisciplina o experiencia para hacerlo bien.

Lo que nunca funciona es "decirles que agreguen más comentarios". Esto no aumentará ni su autodisciplina ni su experiencia. En mi humilde opinión, lo único que podría funcionar es hacer frecuentes revisiones de código y sesiones de refactorización. Cuando un desarrollador haya completado una tarea, permítale explicar cualquier parte del código que no comprenda. Refactorice o documente de inmediato el código de tal manera que ambos lo entiendan 6 meses después.

Haga esto durante un período de unos pocos meses, al menos dos veces por semana. Si tienes la suerte, los otros desarrolladores aprenderán a través de estas sesiones para que puedas reducir la frecuencia de revisión.

Doc Brown
fuente
55
+1 esta es la única forma de implementar el cambio en un colega que he encontrado, siéntate con ellos y revisa / refactoriza junto a ellos. Si no está en condiciones de negar una revisión de código, esto puede ser difícil. A veces, cuando estás en el nivel medio, solo tienes que plantear problemas a las personas de la tercera edad y, si no escuchan, muele la nariz hasta que estés en la tercera edad y puedas vetar esa basura
Jimmy Hoffa
1
Las revisiones de código y la programación de pares son la mejor manera en mi experiencia de mejorar el estándar general de los desarrolladores en un equipo. Se trata de compartir conocimientos y habilidades dentro del equipo. Sin eso, estás haciendo que los desarrolladores aprendan de la manera difícil y suponiendo que salieron perfectos de la universidad. La falta general de esta práctica en la industria es probablemente la razón por la que hay tantos desarrolladores con más de 10 años de experiencia que no pueden escribir código legible y bien organizado.
Martin Brown
27

Me sorprende que nadie haya mencionado revisiones de código todavía. Hacer revisiones de código! Cuando tiene un registro de mala calidad, no solo diga "agregar comentarios". Haga preguntas constantemente y pídale que le diga qué hace su código y por qué. Toma nota. Luego, al final de la revisión del código, dele una copia de las notas y dígale que haga sus preguntas bastante obvias. Ya sea por más comentarios o simplemente refactorizando su código para que sea de mejor calidad (preferiblemente este último cuando sea posible)

Earlz
fuente
2
+1: si tiene que hacer una pregunta sobre cualquier parte del código, entonces esa parte necesita un comentario o una refactorización, por lo que la pregunta no necesita ser formulada por otra persona en el futuro.
Dunk
+1 También las revisiones de código / pares sorprendidas son muy bajas en las respuestas. La implementación de revisiones de código a nivel de equipo (para no molestar a un individuo) podría ayudar a resolver el problema (y tal vez otros que ni siquiera sabe que tiene :). En el extremo, podría implementar una política de no empujar solo por la cual no se le permite empujar a menos que sus cambios hayan sido revisados ​​por otro miembro del equipo.
Chris Lee
@ChrisLee en las políticas de revisión de código de mi empresa no se aplican técnicamente, pero hay una política que, antes de que una historia pueda marcarse como Lista para prueba, debe revisarse el código, sin importar quién realizó el trabajo de desarrollo. Es bastante interesante tener que revisar el código cuando el CTO hace un check in aunque lol
Earlz
18

Esto depende del código que produce su trabajador de equipo. Si lees el libro Clean Code del tío Bob, encontrarás que en realidad prefiere no agregar comentarios al código. Si el código en sí es tan legible como debería ser, casi no hay necesidad de comentarios.

Si ese no es el caso, o si necesita comentarios debido a alguna política no negociable, entonces la pregunta principal es si solo usted quiere que él o ella escriba comentarios, o si es todo el equipo o el equipo / proyecto líder. Si solo eres tú, entonces debes hablar con tus otros colegas para averiguar por qué puede que no sea tan importante.

Si el líder del proyecto no tiene los comentarios, también puede solicitarlos como parte de la integridad , es decir, si el código enviado no tiene comentarios, el trabajo aún no ha finalizado. No puede continuar haciendo otro trabajo, hasta que su trabajo actual esté terminado y para eso se requieran comentarios. Sin embargo, tenga en cuenta que este tipo de forzamiento probablemente generará comentarios horribles (espere un montón de comentarios de código repugnantes).

La única manera factible en mi humilde opinión es discutir las ganancias reales que usted y todos los demás obtienen de los comentarios. Si él / ella no lo entiende por simple discusión, siempre existe el camino difícil: en lugar de dejar que escriban código nuevo, que trabajen en el código existente. Si es posible, debe encontrar dos áreas de trabajo diferentes: una con comentarios útiles adecuados y otra que carece de comentarios. Tener que leer el código no comentado y no legible de otra persona es una revelación con respecto a su propio trabajo.

Todos hemos estado allí una vez y estábamos enojados por el autor original de alguna fuente por trabajar tan descuidadamente. Es la reflexión adicional de que cada uno de nosotros es un autor así que te hace darte cuenta de que debes preocuparte por la legibilidad; por lo tanto, no olvides discutir los resultados con tu colega después para promover esta reflexión.

Franco
fuente
+1 por discutir los beneficios reales de los comentarios. Los comentarios están destinados a agregar valor al código fuente.
Sparky
1
Re: "este tipo de forzamiento probablemente dará como resultado comentarios horribles". Si no está comentando mientras codifica, los comentarios de relleno después de que el código esté hecho casi siempre generarán comentarios horribles, ya sea que crea en ellos o no. Cuando está codificando, ese es el momento en que sabe exactamente POR QUÉ está haciendo algo de una manera particular. Ese es el momento de dejar que otros lo sepan. Si comenta después de terminar, es probable que ni siquiera recuerde lo que estaba pensando cuando escribió el código, por lo que tiende a arrojar un comentario inútil solo por el simple hecho de comentar.
Dunk
3
Siempre tuve un problema con el enfoque de ese libro. Los comentarios pueden ser muy útiles para explicar un proceso / lógica empresarial (o por qué) que no puede hacer una cantidad de código limpio.
bharal
Si bien los comentarios en el código no serían necesarios, debería haber al menos la descripción del método, como Javadoc
Danubian Sailor
2
Clean Code es un libro decente, pero no debe ser tratado como un evangelio. Tienes que aplicar el sentido común y decidir por ti mismo lo que funciona. No estoy de acuerdo con el consejo sobre los comentarios, porque los lenguajes de programación están orientados a expresar el cómo de un problema con poca atención al por qué. Estaba escribiendo un código para Google Shopping que agrega un código de país a la SKU del producto. Es obvio lo que está haciendo el código, pero a menos que sepa que solo puede usar el mismo código de producto una vez, incluso en diferentes mercados, no sabría por qué estaba haciendo esto. El comentario que agregué lo aclara.
GordonM
10

Si tiene un empleado que no puede seguir las instrucciones, repréndalo y asegúrese de que esté claro que no ayudará a que su carrera avance. La consistencia en el estilo de codificación es crítica para un equipo, y si todos los demás escriben comentarios y este no, eso dañará el estilo de codificación.

Dicho esto, probablemente puedas ayudarlo. En mi experiencia, cuando alguien protesta que comentar toma demasiado tiempo, existe una barrera psicológica como ...

  1. Es consciente de sus elecciones de código / diseño y no quiere exponerlas en prosa. (Las revisiones de código pueden ser útiles para reforzar la confianza en sí mismo de alguien tanto como para derribarlo).
  2. Trabaja de manera muy lineal y no piensa mucho en el futuro. Comentar es doloroso porque lo obliga a descargar el código inmediato que estaba a punto de escribir de su memoria de trabajo para componer su intención de una manera diferente. (Si esto es cierto, comentar se vuelve muy importante para la calidad de su código).
  3. Históricamente la gente no entiende sus comentarios.

Es importante que un programador se dé cuenta de que los comentarios son como pruebas: no son solo para uso futuro, son para el programador mismo. Lo obligan a pensar de manera diferente sobre su enfoque.

Nada de esto es un sustituto de CI, pruebas o revisiones de código. Es solo una de las muchas partes críticas de la codificación que es, en sí misma, no escribir código.

kojiro
fuente
3
No creo que las amenazas sean necesariamente efectivas, pueden aparecer como intimidación (incluso si esa no era la intención) y los codificadores, por regla general, tienden a estar resentidos con los edictos de los superiores y, en este caso, puede que simplemente clava los talones aún más. Puede llegar a eso como último recurso, pero solo como último recurso.
GordonM
@GordonM ¿Cree que sería mejor no decirle a un empleado cuándo su comportamiento es inapropiado y cuáles serían las consecuencias de un comportamiento inapropiado continuo?
kojiro
Obviamente, no decir nada no es una buena idea, pero amenazar a las personas solo fomentará un clima de miedo, especialmente por algo relativamente menor, como el estilo de comentarios. Si le explica razonablemente por qué el equipo considera importante comentar, está bien. Pero sé que si alguien me amenazó con el saco por algo relativamente menor, estaría más inclinado a comenzar a buscar otro trabajo.
GordonM
@GordonM De hecho, tomo la excepción de la implicación de que lo que dije era amenazante, pero de todos modos, lo arreglé.
kojiro
8

Obtenga un software de revisión de código y úselo bien.

Usamos Kiln, y nos encanta. Tenemos una política de que cada conjunto de cambios debe revisarse (aunque permitimos que los desarrolladores aumenten / aprueben revisiones por sí mismos en etiquetas y fusiones sin conflictos (aunque la mayoría de nosotros usamos rebaseif); de esta manera podemos detectar rápidamente conjuntos de cambios sin revisiones).

El código que no está claro es motivo para rechazar una revisión de código. No importa si la solución son comentarios o un código más claro, pero el revisor debe poder entenderlo. Algunos desarrolladores prefieren reescribir el código, pero a otros (incluido yo mismo) a menudo les resulta más fácil expresar la intención en los comentarios (el código puede mostrar fácilmente lo que hace, pero es más difícil mostrar lo que debería hacer).

Si alguna vez hay dudas sobre la claridad del código, el revisor siempre gana. Por supuesto, el autor lo entiende, porque lo escribieron. Tiene que estar claro para otra persona.

Al usar software como Kiln, no se pasa por alto ningún conjunto de cambios. Todos en mi equipo de desarrollo lo prefieren mucho de esta manera. El software de revisión de código ha tenido un gran impacto tanto en la calidad de nuestro código como en la calidad de la aplicación :-)

Es fácil para los desarrolladores ponerse a la defensiva con revisiones rechazadas cuando introducen el software por primera vez, pero en mi experiencia, no les lleva mucho tiempo darse cuenta de que las cosas son mejores de esta manera y aceptarlas :-)

Editar: También vale la pena señalar, intentamos que los desarrolladores no expliquen el código críptico verbalmente o en los comentarios de la revisión. Si algo no está claro, el mejor lugar para explicarlo es en el código (en comentarios o refactorizando), luego agregue los nuevos conjuntos de cambios a la misma revisión.

revs Danny Tuppeny
fuente
4

Interesante, que la legibilidad aplicada al lenguaje natural se mide por la velocidad de lectura y comprensión. Supongo que se puede adoptar una regla simple, si un comentario de código en particular no mejora esta propiedad, se puede evitar .

¿Por qué comentarios?

Aunque el comentario de código es una forma de documentación incorporada, existen múltiples maneras en los lenguajes de programación de alta gama para evitar la programación superflua "sobredocumentada" (de código significativo) mediante el uso de elementos del lenguaje en sí. También es una mala idea convertir el código en listados del libro de texto de programación, donde las declaraciones individuales se explican literalmente de manera casi tautológica (tenga en cuenta el ejemplo "/ * increment i by 1 * /" en respuestas ya proporcionadas), haciendo que tales comentarios sean relevantes solo para programadores inexpertos con el lenguaje.

Sin embargo, es la intención de tratar de comentar el código "poco documentado" (pero sin sentido) que es realmente "la fuente de todo mal". La existencia misma del código "poco documentado" es una mala señal, ya sea un desastre no estructurado o un truco loco de propósito místico perdido. Obviamente, el valor de dicho código es cuestionable al menos. Desafortunadamente, siempre hay ejemplos, cuando de hecho es mejor introducir un comentario en una sección de líneas de código formateadas (visualmente agrupadas) que envolverlo en una nueva subrutina (tenga en cuenta la "consistencia tonta" que "es el duende de las pequeñas mentes") .

Legibilidad de código! = Comentarios de código

El código legible no requiere anotaciones por comentarios. En cada lugar particular en el código siempre hay un contexto de una tarea que se supone que este código particular debe lograr. Si falta el propósito y / o el código hace algo misterioso = evítelo a toda costa. No permita que hacks extraños llenen su código: es un resultado directo de combinar tecnologías defectuosas con falta de tiempo / interés para comprender los fundamentos. ¡Evita el código místico en tu proyecto!

Por otro lado, el programa legible = código + documentación puede contener múltiples secciones legítimas de comentarios, por ejemplo, para facilitar la generación de documentación de "comentarios a la API".

Siga los estándares de estilo de código

Curiosamente, la pregunta no es por qué comentar el código, se trata del trabajo en equipo, cómo producir código en un estilo altamente sincronizado (que todos los demás puedan leer / comprender). ¿Sigue alguna norma de estilo de código en su empresa? Su objetivo principal es evitar escribir código que requiere refactorización, es demasiado "personal" y "subjetivamente" ambiguo. Entonces, supongo que si uno ve la necesidad de usar el estilo de código, hay una gran cantidad de herramientas para implementarlo correctamente, comenzando con la educación de las personas y terminando con la automatización para el control de calidad del código (numerosas líneas, etc.) y (revisión control integrado) sistemas de revisión de código.

Conviértete en un evangelista de legibilidad de códigos

Si acepta que el código se lee con más frecuencia de lo que se escribe. Si la expresión clara de las ideas y el pensamiento claramente es importante para usted, no importa qué idioma se use para comunicarse (matemática, código de máquina o inglés antiguo). Si su misión es erradicar la forma aburrida y fea de pensamiento alternativo. , el último es de otro "manifiesto") ... haga preguntas, inicie discusiones, comience a difundir libros que provoquen pensamientos sobre la limpieza de códigos (probablemente no solo algo similar a los patrones de diseño de Beck, sino más como ya lo mencionó RC Martin ) que abordan la ambigüedad en la programación Además va un pasaje con viñetas de ideas clave (citado del libro de O'Reilly sobre legibilidad)

  • Simplifique la nomenclatura, los comentarios y el formato con sugerencias que se aplican a cada línea de código.
  • Refine los bucles, la lógica y las variables de su programa para reducir la complejidad y la confusión.
  • Atacar problemas a nivel de función, como reorganizar bloques de código para hacer una tarea a la vez
  • Escriba un código de prueba efectivo que sea completo y conciso, así como legible

Eliminando los "comentarios", todavía queda mucho (¡supongo que escribir código que no necesita comentarios es un gran ejercicio!). Nombrar identificadores semánticamente significativos es un buen comienzo. Luego, estructura tu código agrupando operaciones conectadas lógicamente en funciones y clases. Y así. Un mejor programador es un mejor escritor (por supuesto, asumiendo otras habilidades técnicas dadas).

Yauhen Yakimovich
fuente
Puede escribir código que no necesita comentarios solo por diversión. De hecho, este podría ser un gran ejercicio, pero no si necesita volver al código y realmente no puede cambiar nada porque no sabrá por qué funciona esta función, ya que tal vez hubo algún cliente que lo quería así. Por supuesto, puede estar en ese quizás el 1% del proyecto que está documentado y razonado fuera del proyecto, pero incluso entonces hay decisiones que toma durante la codificación que no se vuelven a la documentación. Y francamente ... ¿Quién lee la documentación que no está en el código? Ciertamente no programadores ;-P.
Nux
1
Un buen ingeniero se preocupa por todo el sistema (incluida la documentación no generada por código), pero aquí, por supuesto, nos importa la codificación en general. Mi punto es que no tener identificadores en el código llamados foo , bar , tmpSomething2 e IamJustTooSmartAssToCare ya mejora la situación y reduce la necesidad general de explicar qué es el código y qué hace. El código debe escribirse con "modo de pensamiento activado" como una API bien diseñada que los humanos leen, comprenden, reutilizan y mantienen. ¡Demasiados comentarios en el código que de otra manera serían difíciles de entender es una muy mala señal!
Yauhen Yakimovich
Por cierto, programar / codificar cualquier tipo de lógica específica de dominio en forma de un HACK o una corrección de error "temporal" de hecho está produciendo "HACK extraños", tan pronto como haya muchos de ellos metidos dentro de la caja negra, espere que fallar y devolver el fuego. Esto puede justificarse por plazos en los proyectos del "mundo real", etc. pero en realidad es solo un software barato que requiere la remodelación de la lógica de dominio (o tal vez encontrar un nuevo trabajo).
Yauhen Yakimovich
Estoy de acuerdo en que la legibilidad es importante, lo que no estoy de acuerdo es que pareces decir "si haces de la legibilidad una prioridad, no necesitarás comentarios". Eso simplemente no es cierto. He estado allí hecho eso. Razonar lo que haces no solo viene de nombrar variables de una manera que tenga sentido. Haga eso, por supuesto, pero también agregue razón en los comentarios (incluso si está en forma de un número de error / requisito / historia en algún sistema externo). Eso es lo que estoy diciendo.
Nux
"Si hace que la legibilidad sea una prioridad, no necesitará comentarios". Sí, esto es exactamente lo que estoy diciendo (y sé que esto no parece fácil de lograr). Por cierto, ¿tiene situaciones en las que mantener el historial completo de confirmación (control de versiones) no es suficiente para reflejar el "número de error / requisito / historia"? He estado practicando confirmaciones bastante largas, funciona para mí y permite mantener el código vacío del historial de desarrollo ... lo hace menos orgánico.
Yauhen Yakimovich
3

¿Me equivoco al centrarme en los comentarios del código o esto es indicativo de un problema mayor que debería abordarse?

Algo. Un gran código no necesita comentarios. Sin embargo, como dijiste, su código no se documenta automáticamente. Entonces no me enfocaría en los comentarios. Debes concentrarte en mejorar la habilidad y la artesanía de tus desarrolladores.

Entonces, ¿cómo hacer eso? Las sugerencias de Doc Brown sobre las sesiones de revisión / refactorización son una buena idea. Encuentro la programación de pares aún más efectiva, pero también puede ser considerablemente más difícil de implementar.

Pete
fuente
La programación en pareja es una excelente idea, le da a otro programador una idea del desarrollo del código para que sepan lo que está sucediendo, haciendo que dos personas sean responsables del código. también le da la oportunidad a uno de los dos de decir que algo debería tener un comentario porque está fuera de lo común o algo que alguien más podría cambiar porque parece ... "una pérdida de memoria", "mala codificación", etc. algunas cosas necesitan comentarios para que otra persona en el futuro no deshaga algo porque no se ve bien.
Malaquías
3

En primer lugar, te sugiero que vuelvas a abordar tu enfoque sobre los comentarios.

Si se trata de comentarios de documentación a nivel de API (expuestos más tarde al público), entonces este desarrollador simplemente no está haciendo su trabajo. Pero para todos los demás comentarios, tenga cuidado.

En la mayoría de los casos los encuentro, los comentarios son malos. Recomendaría leer el capítulo de comentarios de código de "Código limpio" de Robert Martin para comprender por qué.

Los comentarios dañan su código de varias maneras:

1) Son difíciles de mantener. Tendrás que hacer un trabajo extra al refactorizar; Si cambia la lógica descrita en el comentario, también debe editar el comentario.

2) A menudo mienten. No puede confiar en los comentarios y debe leer el código en su lugar. Lo que plantea la pregunta: ¿por qué necesitarías los comentarios?

// this method returns the sum of 'a' and 'b'
public int GetHash(int a, int b)
{
    //the calculation of the hash
    int result = a*b;
}

(El hash no es la suma sino el producto).

3) Los comentarios desordenan el código y muy rara vez agregan algún valor.

Mi solución: en lugar de agregar más comentarios, ¡intenta deshacerte de ellos!

Paul
fuente
44
Esto es una tontería. Espero que nadie crea que un estilo de comentario tan pobre es útil. ¿Pero honestamente crees que los comentarios nunca deberían usarse?
jmk
1
Sí, esta es una sugerencia tonta, si el código es increíblemente legible, podría entender algunos comentarios, pero ver comentarios debería decir por qué el método está haciendo lo que es y dónde se usará una vez que llegue a más de unas pocas clases. No hay razón para no hacer comentarios, ayudan a todos.
DBlackborough
3
Lo importante para recordar es que si bien todo tiene sentido para usted en este momento, alguien más tendrá que mantener su código en 3 años. No jodas el sobre.
xaxxon
44
@xaxxon Sin mencionar que las manzanas, incluso si esa persona podría ser usted.
esponjoso
3
@mehaase: no es qué, no cómo, pero por qué es la razón más importante para agregar comentarios al código.
Henk Langeveld
1

Si un miembro del equipo tiene problemas para comprender el código de otro miembro del equipo (por cualquier motivo); entonces, ese miembro del equipo debería poder averiguar quién escribió el código original (cualquier sistema de control de revisión sensato) y debería alentarse a pedirle al autor del código que lo explique directamente (por ejemplo, diríjase a su escritorio, siéntese y hable sobre él).

En este caso, si la falta de comentarios es un problema, la persona que no está comentando adecuadamente su código pasará una gran cantidad de tiempo explicando lo que ha hecho; y (si son inteligentes) comenzarán a agregar comentarios para evitar perder tiempo en todas esas explicaciones.

Tenga en cuenta que alentar a los miembros del equipo a pedirse explicaciones es valioso por otros motivos. Por ejemplo, quizás un miembro del equipo tiene menos experiencia y puede aprender cosas de los miembros más experimentados del equipo.

Principalmente, al alentar a los miembros del equipo a que se pidan explicaciones, crean un sistema de auto-equilibrio; donde los diferentes miembros del equipo se "ajustan automáticamente" entre sí.

Brendan
fuente
1

Esta es en gran medida una extensión de la respuesta de tdammers, pero realiza revisiones de código a intervalos regulares.

Hacer que él (y otros desarrolladores) se siente, revise su código y se defienda más o menos frente a sus superiores y compañeros hará que todos sean mejores programadores y agregará un valor real en un período de tiempo relativamente corto. A corto plazo, no le dará al desarrollador en cuestión ninguna excusa para, en el momento de la revisión, comentar adecuadamente su código.

EDITAR: no estoy seguro de por qué alguien rechazaría mi sugerencia; tal vez di por sentado que los beneficios de la revisión del código serían de conocimiento común ... vea este hilo para un análisis comunitario de la práctica:

¿El código revisa las buenas prácticas?

LJ2
fuente
Cuando una sala llena de gente comienza a reírse de su código ilegible, comenzará a hacer un mejor trabajo de codificación y comentarios. :) Soy un gran defensor de las revisiones de código.
Evik James
1
Hacer que la gente se ría del código frente a otros colegas no es la forma de hacerlo: - \
Danny Tuppeny 05 de
1
Si las personas que realizan la revisión del código se ríen en lugar de ser constructivas, necesitan capacitación tanto como un desarrollador que no puede escribir código legible. Hacer una crítica constructiva en lugar de despectiva es una de las habilidades sociales que encuentro que los desarrolladores a menudo carecen.
Martin Brown
1

Teniendo en cuenta las opiniones a menudo extremas sobre los comentarios, dudo en opinar. Dicho esto ...

¿Cuáles son algunos argumentos que puedo presentar que si va a escribir código (ilegible) que debería documentarse correctamente?

Comprender cómo escribir código fácil de mantener requiere tiempo, práctica y experiencia. Los programadores sin experiencia (y lamentablemente muchos experimentados) a menudo sufren el efecto Ikea ( PDF ). Eso se debe a que lo construyeron y están íntimamente familiarizados con él, y están seguros de que el código no solo es excelente, sino también legible.

Si la persona es un gran programador, entonces se requiere poca o ninguna documentación. Sin embargo, la mayoría de los programadores no son geniales y gran parte de su código sufrirá en el departamento de "legibilidad". Pedirle al programador mediocre o en desarrollo que "explique su código" es útil porque los obliga a ver su código con un ojo más crítico.

¿Esto significa "documentar" su código? No necesariamente. Caso en cuestión, tuve un programador similar con este problema en el pasado. Lo forcé a documentar. Lamentablemente, su documentación era tan indescifrable como su código, y no agregaba nada. En retrospectiva, las revisiones de código habrían sido más útiles.

Usted (o un delegado) debe sentarse con este programador y extraer parte de su código anterior. No son las cosas nuevas que él conoce simplemente trabajando en ello. Debe pedirle que lo guíe a través de su código con una interacción mínima. Esto también podría ser una sesión de "documentación" separada, donde él debe explicar por escrito su código. Entonces debería recibir comentarios sobre mejores enfoques.

Además, a veces se necesita cierta documentación, independientemente de cuán buena sea la "legibilidad" del código. Las API deben tener documentación, las operaciones extremadamente técnicas y complejas deben tener documentación para ayudar al programador a comprender los procesos involucrados (a menudo fuera del dominio del conocimiento de los programadores), y algunas cosas como expresiones regulares complejas realmente deberían documentar con qué se compara.

Bill
fuente
0

Muchos proyectos requieren documentación de código: documento de interfaz, documento de diseño, ...

Algunos proyectos requieren que dicha documentación se ponga en comentarios de código y se extraiga con herramientas como Doxygen o Sphinx o Javadoc, para que el código y la documentación se mantengan más consistentes.

De esa manera, los desarrolladores deben escribir comentarios útiles en el código y este deber está integrado en la planificación del proyecto.

Mouviciel
fuente
66
No, de esa manera los desarrolladores deben escribir algunos comentarios. Su utilidad disminuye con la presión de escribirlos, y a menudo se hunde por debajo de cero en la región activamente dañina (un comentario inválido es peor que ningún comentario) si la política se empuja con fuerza.
Jan Hudec
1
@ JanHudec - Estoy de acuerdo contigo. Es por eso que se debe establecer algún control. La generación automática garantiza que, por ejemplo, los argumentos de la función en el código sean los mismos que en los comentarios. Además, tener un solo PDF en lugar de un directorio de archivos fuente hace que la documentación sea más legible (es decir, más revisable) por más personas.
Mouviciel
2
Bueno, no, no lo hace. ¿Cómo notará en el .pdf que el código realmente hace algo sutilmente diferente de lo que dice la descripción?
Jan Hudec
1
Tal vez mi opinión está sesgada por mi dominio, software de espacio crítico donde todo se revisa, controla, verifica, prueba dos o tres o cuatro veces. La generación automática de documentación no elimina las inconsistencias, pero ayuda a reducirlas.
Mouviciel
Sí, eres muy parcial. En dominios como ese tiene sentido, en la mayoría de las pruebas unitarias son suficientes para el control de calidad y documentar cada última función sería una pérdida de tiempo.
Jan Hudec
0

Voy a decir a qué apuntan la mayoría de las respuestas y comentarios: probablemente necesite descubrir el problema real aquí en lugar de tratar de impulsar su solución percibida.

Estás motivado para ver comentarios en su código; ¿Por qué ? Diste una razón; ¿ Por qué es esa razón tan importante para ti? Él está más motivado para hacer otra cosa; ¿Por qué ? Él dará una razón; ¿ Por qué esa razón es tan importante para él? Repita esto hasta llegar al nivel donde realmente surge el conflicto, e intente encontrar una solución con la que ambos puedan vivir. Apuesto a que tiene muy poco que ver con comentar.

reinierpost
fuente
0

Si sigue un buen estándar de codificación, se requerirá un número mínimo de comentarios. las convenciones de nombres son importantes. Los nombres de métodos y nombres de variables deben describir su función

Mi TL me sugiere que use menos comentarios. quiere que mi código sea comprensible y autodescriptivo. ejemplo simple: nombre de variable para el tipo de cadena que se usa para el patrón de búsqueda

   var str1:String="" //not uderstandable
   var strSearchPattern:String="" //uderstandable
revs M.S.Nayak
fuente
0

Me encantan las respuestas de revisión de código, pero quizás mi proceso también ayudará un poco.

Me encantan los comentarios, pero casi nunca los agrego al código en la primera pasada. Tal vez sea solo mi estilo, pero llegaré a la misma sección del código de 3 a 5 veces durante el desarrollo (refactorización, pruebas de escritura, etc.).

Cada vez que me confundo un poco o cuando alguien me hace una pregunta sobre una sección de código, intento solucionarlo para que tenga sentido.

Esto puede ser tan simple como agregar un comentario eliminando un conjunto confuso de operaciones en su propia función o puede desencadenar un refactor más grande como extraer un nuevo objeto.

Sugiero que aliente a todos en el grupo a "reconocer" que su código es legible para otros, esto significa que cada vez que alguien le hace una pregunta sobre su código, se compromete a hacer un cambio, o mejor aún, emparejarlo persona para hacer el cambio en ese momento!

Considere seriamente presionar para esto como parte de su "Contrato de equipo" (y definitivamente cree un contrato si no tiene uno), de esa manera todos lo han acordado y usted lo tiene en una pared en algún lugar para que no haya Cualquier pregunta sobre lo que ha acordado hacer.

Bill K
fuente
0

Tal vez este tipo necesita una apreciación de la buena disciplina de codificación, y por qué es importante que otras personas puedan entender el código que ha escrito.

He trabajado en algunas bases de código realmente horribles en mi carrera, en las que el código estaba tan mal organizado, los nombres de las variables eran tan pobres, los comentarios eran tan malos o inexistentes que la base de códigos perjudicaba mi productividad. No puedes trabajar para arreglar o mejorar una base de código que no entiendes, y si está escrita de una manera que sea impenetrable para los recién llegados, pasarán más tiempo tratando de entenderla que trabajando realmente en ella.

¡No hay mejor maestro que una experiencia dura!

Cada código base tiene algunas partes horribles al acecho, partes del sistema que nadie quiere tocar porque tienen miedo de romper algo, o no pueden hacer ningún trabajo significativo porque quien escribió el código se ha ido y ha entendido del código con ellos. Si ese código no está comentado y no se documenta automáticamente, solo empeora las cosas.

Le sugiero que encuentre la parte de su base de código que sea así y que le dé a su codificador problemático la responsabilidad de ello. Dele la propiedad de él, hágalo su responsabilidad, déjelo aprender el verdadero dolor de trabajar en un código que no se puede mantener porque no está bien documentado o es imposible de entender en un corto espacio de tiempo. Después de unos meses trabajando en ello, estoy seguro de que comenzará a volver.

GordonM
fuente
-1

Dele otro código sin comentarios y pídale que entienda el código. Puede ser que él comprenda la importancia de los comentarios apropiados entonces.

Abhishek Gahlout
fuente
12
Apenas evité el botón -1 en esto. La mayor parte del código que escribo tiene muy pocos comentarios. No creo que haya tenido personas quejándose de que no es comprensible en los últimos años al menos. Con muy pocas excepciones, si el código necesita comentarios para ser entendido , entonces no necesita comentarios, necesita mejoras para mayor claridad. (Por supuesto, debe asumir una comprensión básica de la sintaxis del lenguaje. Cosas como, en C ++, no se salga de su camino simplemente para evitar usarlo reinterpret_cast<>()porque las personas pueden encontrarlo confuso; en C #, si ??hace lo que necesita, use it; etc.)
un CVn
2
@ MichaelKjörling: Puede depender en gran medida del tipo de código que esté escribiendo. Si su código depende de características poco comunes de un lenguaje o una API, o si hizo algo de forma contra-intuitiva para evitar un error oscuro que le llevó horas descubrir, sería mucho más efectivo comentar sobre (posiblemente incluyendo un enlace a un artículo) que intentar hacer que el código sea "claro" sobre esta información de fondo sin comentarios.
LarsH
@ MichaelKjörling: Estoy especialmente motivado para decir eso hoy porque he estado luchando durante el último mes con una API SIG profunda. Las instalaciones de la API son complejas y no están muy bien documentadas. Constantemente nos encontramos con sorpresas, algunas de las cuales nos retrasan días a la vez. Esperar que alguien más (o yo en 6 meses) tenga que redescubrir esas pepitas para trabajar de manera efectiva con nuestro código sería una gran pérdida de tiempo para esa persona. Y esos secretos generalmente no pueden documentarse mediante una "mejora para la claridad" sin comentarios.
LarsH
@LarsH Eso probablemente calificaría como una de esas "muy pocas excepciones" que mencioné en mi comentario. No estoy en contra de comentar dónde realmente agrega valor ; pero no es la cantidad de comentarios lo que hace que el código sea fácil o difícil de leer. Dicho esto, con una API, estaría más inclinado a documentar esas peculiaridades en otros lugares; digamos, en una wiki o similar. Quizás también agregue un enlace a la página relevante al lado de cada uso. De esa manera, no tiene que buscar otro lugar que use esa característica particular de la API siempre que el código no funcione como espera en el primer intento.
un CVn
@ MichaelKjörling: acordado en general. Si estas excepciones son raras o no, depende del dominio para el que esté programando y de las API que debe usar. Los enlaces / referencias son buenos para las notas que se aplican en general, no solo a la situación actual. Nadie quiere una disertación en el código mismo.
LarsH
-1

¿Este programador hace algún mantenimiento de código? De lo contrario, debe: verificar si hay algún proyecto que no le guste y asignarle su mantenimiento.

Por lo general, esos son los proyectos mal documentados en los que pierde horas tratando de comprender lo que está sucediendo para corregir lo que podría haber sido fácil de corregir. Si este tipo de experiencia no lo hace desear una documentación actualizada y útil, nada lo hará.

Arkh
fuente
1
Es más probable que este enfoque haga que el programador renuncie en lugar de entrenarlo en la forma adecuada de hacer las cosas.
Martin Brown
-1

En uno de mis proyectos anteriores faltaban docenas de comentarios (algoritmo, resultados o algunos JavaDoc básicos), así que decidí hacer 130 problemas para él, notificación por correo electrónico sobre cada uno de los problemas cada 4 días. Después de 3 semanas tuvo 280 problemas, luego decidió escribir comentarios.

agilob
fuente
-1

Los comentarios tienen un propósito y un solo propósito:

¿Por qué este código hace esto?

Si un comentario no explica por qué algo es como es, entonces debe eliminarse. Los comentarios inútiles que desordenan el código son menos que inútiles, son activamente dañinos.

Tengo la costumbre de hacer que mis comentarios sean lo más obvio en mi IDE. Se resaltan con texto blanco sobre un fondo verde. El realmente llama tu atención.

Esto se debe a que el código explica qué está haciendo algo, y los comentarios son sobre por qué lo está haciendo. No puedo enfatizar esto lo suficiente.

Un buen ejemplo de un comentario:

/* Must instantiate clsUser before trying to encrypt a password because the code to 
   encrypt passwords only uses strong encryption if that module is loaded. */

Un mal ejemplo:

/* instantiate clsUser */

Si está utilizando comentarios como "secciones" de código: Divida su método gigantesco en funciones más pequeñas y útiles, y elimine los comentarios.

Si está diciendo lo que está haciendo en la siguiente línea: haga que el código se explique por sí mismo y elimine el comentario.

Si está utilizando comentarios como mensajes de advertencia: asegúrese de decir por qué.

Jonathan
fuente
-2

Para complementar las respuestas aquí, podría agregar: "Si desea que se haga bien, debe hacerlo usted mismo".

No me refiero a convertirme en "principal comentarista de código", me refiero a convertirme en un modelo a seguir para demostrar lo que le gustaría que haga este otro desarrollador. Dicen que mostrar es más efectivo que contar . Si puede demostrar el beneficio de los comentarios de calidad, o incluso asesorar a este otro desarrollador (en la medida en que él lo desee), puede encontrar más éxito en la adopción de comentarios de código.

Del mismo modo, en casa hay algunas tareas domésticas que no me interesan. Sin embargo, esos mismos quehaceres son los quehaceres favoritos de mi esposa ... deberes que deben hacerse para que ella sea feliz. La misma situación se aplica al revés. Creo que debe aceptar que este otro desarrollador tiene prioridades diferentes a las suyas y no estará de acuerdo con usted en todo. La solución que hemos encontrado mi esposa y yo es que para esas tareas domésticas, solo tenemos que hacerlas nosotros mismos, incluso si eso significa trabajar un poco más por nuestra cuenta.

M. Dudley
fuente
1
Yo diría que mostrar un código más limpio / refactorizar su código para que sea más legible demuestra un cambio mayor que poner montones de comentarios en el código.
Makoto
¿Alguien puede explicarme lo que no les gusta de mi idea ...?
M. Dudley
-6

Simple: si el empleado no hace comentarios, dígale que presione shift+alt+jpara comentarios automáticos en cada método simultáneamente al ingresar el código. revise el código para evitar estos problemas.

peter
fuente
11
"¿Comentario automático"? Entonces, ¿ de dónde provienen todos esos comentarios de "incrementar i por 1"? ¿Qué IDE hace esto (para que pueda evitar trabajos donde se está usando)?
un CVn
Traté de editar esto en algo legible, pero no estoy seguro de si la palabra primero debe tener una coma antes o después. ¿Es la frase hacer comentarios primero o primero decir en cada método ?
TRiG