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

Los comentarios por sí solos no hacen un mejor código, y solo presionar para obtener "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 entienda por qué.

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

Así que no se queje por los comentarios faltantes: se queja por un código ilegible. O mejor aún, no se queje, solo haga preguntas sobre el código. Para cualquier cosa que no entiendas, pregunta a la persona que lo escribió. Deberías estar haciendo eso de todos modos; Con código ilegible, solo harás más preguntas. Y si regresa a un fragmento de 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 en funcionamiento, en algún momento se dará cuenta de que comentar el código es mucho más fácil que tenerte cerca 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 con sus preguntas.

He conocido a muchos desarrolladores que tuvieron problemas para escribir un código de auto-documentación 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á su autodisciplina o experiencia. En mi humilde opinión, lo único que podría funcionar es hacer revisiones de código frecuentes y amp; Sesiones de refactorización. Cuando un desarrollador haya completado una tarea, permítale que le explique cualquier parte del código que no entienda. Inmediatamente refactorice o documente el código de tal manera que ambos lo comprendan 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.

Me sorprende que nadie haya mencionado el código aún. Hacer revisiones de código! Cuando tenga un registro de mala calidad, no se limite a decir "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, déle una copia de las notas y dígale que haga sus preguntas bastante obvias. Ya sea por más comentarios o simplemente por refactorizar su código para hacerlo de mejor calidad (preferiblemente lo último cuando sea posible)

Esto depende del código que produzca su trabajador del equipo. Si lees el libro Clean Code del Tío Bob, descubrirás que realmente prefiere no agregar comentarios al código. Si el código en sí es tan legible como debería ser, entonces 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 es solo usted quien quiere que él / ella escriba comentarios, o si Es todo el equipo o el equipo / líder del proyecto. Si solo eres tú, entonces deberías hablar con tus otros colegas para averiguar por qué puede que no sea tan importante.

Si el líder del proyecto carece de los comentarios, también puede solicitarlos como parte de integridad , es decir, si el código enviado carece de comentarios, el trabajo aún no está terminado. Puede que no continúe haciendo otro trabajo, hasta que se termine su trabajo actual y para eso se requieren comentarios. Sin embargo, tenga en cuenta que este tipo de forzamiento probablemente resultará en comentarios horribles (espere un montón de comentarios de repetición de códigos de mierda).

La única forma viable en mi humilde opinión es discutir los beneficios reales que usted y todos los demás obtienen de los comentarios. Si él / ella no lo entiende por simple discusión, siempre existe la manera más difícil: en lugar de dejar que escriban un código nuevo, pídales que trabajen en el código existente. Si es posible, debería encontrarlas en dos áreas de trabajo diferentes, una con comentarios útiles y otra que carezca de comentarios. Tener que leer el código no comentado 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 descuidado. Es la reflexión adicional de que cada uno de nosotros es un autor así que te hace darte cuenta de que deberías preocuparte por la legibilidad, por lo tanto, no te olvides de discutir los resultados con tu colega para promover esta reflexión.

Si tienes un empleado que no puede seguir las instrucciones, repréndelo y asegúrate de que quede claro que no le ayudará a avanzar en su carrera. 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 afectará el estilo de codificación.

Dicho esto, probablemente puedas ayudarlo. En mi experiencia, cuando alguien protesta porque comentar lleva demasiado tiempo hay una barrera psicológica como ...

1. Es consciente de sus elecciones de código / diseño y no quiere ponerlas en prosa. (Las revisiones de códigos pueden ser útiles para reforzar la confianza en sí mismo de una persona y para derribarla).
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, los comentarios son muy importantes para la calidad de su código).
3. Históricamente, las personas no entienden sus comentarios.

Es importante para un programador darse cuenta de que los comentarios son como pruebas: no son simplemente para uso futuro, son para el programador. 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.

Obtenga el software de revisión de código y utilícelo bien.

Usamos Kiln, y nos encanta. Tenemos la política de que cada conjunto de cambios debe revisarse (aunque permitimos que los desarrolladores realicen / 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). / p>

El código que no está claro es motivo para que se rechace una revisión de código. No importa si la corrección es comentarios o código más claro, pero el revisor debe ser capaz de entenderlo. Algunos desarrolladores prefieren volver a escribir el código, pero a otros (yo incluido) 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 que el autor lo entiende, porque lo escribieron. Debe ser claro para otra persona.

Al utilizar software como Kiln, ningún conjunto de cambios se pasa por alto. Todos en mi equipo de desarrolladores lo prefieren 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 las revisiones rechazadas cuando introducen el software por primera vez, pero según mi experiencia, no les toma mucho tiempo darse cuenta de que las cosas están mejor de esta manera y abrazarlas :-)

Editar: También vale la pena mencionar, 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 refactorización), luego agregue los nuevos conjuntos de cambios a la misma revisión.

  

¿Me equivoco al centrarme en los comentarios del código o es este un indicio de un problema mayor que debe abordarse?

Algo. Gran código no necesita comentarios. Sin embargo, como usted dijo, su código no es auto-documentado. Así que no me centraría en los comentarios. Debes centrarte en mejorar la habilidad y la destreza de tus desarrolladores.

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

Interesante, 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?

Si bien, el comentario de código es una forma de documentación incorporada, existen múltiples formas en los lenguajes de programación de alto nivel para evitar la programación superflua "sobre documentada" (de código significativo) utilizando elementos del propio lenguaje. 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 forma casi tautológica (tenga en cuenta el ejemplo "/ * increment i by 1 * /" en las respuestas ya proporcionadas), por lo que dichos comentarios son relevantes. Solo para programadores inexpertos con el lenguaje.

No obstante, es la intención de tratar de comentar el código "no documentado" (pero sin sentido) que es verdaderamente "la fuente de todo mal". La existencia misma de un código "insuficientemente documentado" es una mala señal, ya sea un desorden no estructurado o un truco descabellado de propósitos místicos perdidos. Obviamente, el valor de dicho código es cuestionable al menos. Desafortunadamente, siempre hay ejemplos, cuando es mejor introducir un comentario en una sección de líneas de código (agrupadas visualmente) que envolverlo en una nueva subrutina (tenga en cuenta la "consistencia tonta" que "es el duende de las mentes pequeñas") .

Código legible = código comentarios

El código legible no requiere anotaciones de comentarios. En cada lugar particular del 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 trucos extraños llenen su código; es el resultado directo de la combinación de tecnologías de buggy con falta de tiempo / interés para comprender las bases. ¡Evita el código místico en tu proyecto!

Por otra parte, Programa legible = código + documentación puede contener varias secciones legítimas de comentarios, por ejemplo. para facilitar la generación de documentación "comentarios a API".

Siga los estándares de estilo de código

Lo suficientemente gracioso es que la pregunta no es sobre por qué comentar el código, se trata del trabajo en equipo: cómo producir código en estilo altamente sincronizado (que todos los demás pueden leer / entender). ¿Está siguiendo algún estándar de estilo de código en su empresa? Su propósito principal es evitar escribir código que requiera refactorización, es demasiado "personal" y "subjetivamente" ambiguo. Así que supongo que, si uno ve la necesidad de usar el estilo de código, hay una gran variedad de herramientas para implementarlo correctamente, comenzando por educar a las personas y terminando con la automatización para el control de calidad del código (numerosas ediciones, etc.) y (revisión). control integrado) sistemas de revisión de código.

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

Si acepta que el código se lee con más frecuencia de lo que está escrito. Si una expresión clara de ideas y pensamiento es importante para usted, no importa qué lenguaje se use para comunicarse (matemáticas, código de máquina o inglés antiguo). Si su misión es erradicar una forma aburrida y fea de pensamiento alternativo ... (lo siento , el último es de otro "manifiesto") .. haga preguntas, inicie discusiones, comience a difundir libros sobre la limpieza de códigos (probablemente no sea algo similar a los patrones de diseño de Beck, sino más bien a los ya mencionados by RC Martin ) que aborda la ambigüedad en la programación. Además, se incluye un pasaje de puntos clave de ideas clave (citado en el libro O'Reilly sobre legibilidad)

• Simplifique la asignación de nombres, 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
• Problemas de ataque en el nivel de la función, como reorganizar bloques de código para realizar una tarea a la vez
• Escriba un código de prueba efectivo que sea exhaustivo y conciso, además de legible

Cortar "comentar", a uno todavía le queda mucho (supongo que escribir código que no necesita comentarios es una pieza de gran ejercicio). Nombrar identificadores semánticamente significativos es un buen comienzo. Luego, estructurando su 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).

En primer lugar, le sugiero que vuelva a abordar su enfoque sobre los comentarios.

Si son 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 que los encuentro, los comentarios son malos. Recomendaría leer el capítulo de comentarios sobre el código de "Código limpio" de Robert Martin para comprender bien por qué.

Los comentarios dañan tu 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) Mienten a menudo. No puedes confiar en los comentarios y debes 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 saturan 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!

Si un miembro del equipo tiene problemas para entender el código de otro miembro del equipo (por cualquier motivo); luego, ese miembro del equipo debe poder averiguar quién escribió el código original (cualquier sistema de control de revisión sano) y se le debería alentar a pedirle al autor del código que lo explique directamente (por ejemplo, caminar hasta su escritorio, sentarse y discutirlo).

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

Tenga en cuenta que animar a los miembros del equipo a que se pidan explicaciones entre sí es valioso por otras razones. Por ejemplo, tal vez un miembro del equipo tenga menos experiencia y pueda aprender cosas de los miembros más experimentados del equipo.

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

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

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

EDITAR: No estoy seguro de por qué alguien rechazaría mi sugerencia; quizás doy por sentado que los beneficios de la revisión del código serían de conocimiento común ... vea este hilo como un análisis de la comunidad sobre la práctica:

¿El código es una buena práctica?

Teniendo en cuenta los puntos de vista a menudo extremos sobre los comentarios, vacilo en opinar. Dicho esto ...

  

¿Cuáles son algunos argumentos que puedo presentar que si vas a   escriba el código (ilegible) para que se documente correctamente?

Comprender cómo escribir código mantenible y legible requiere tiempo, práctica y experiencia. Los programadores inexpertos (y tristemente muchos experimentados) a menudo sufren el Efecto Ikea ( PDF ) . Esto 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 que también es 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 "lectura". 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. Por ejemplo, tuve un programador similar con este problema en el pasado. Le obligué a documentar. Desafortunadamente, su documentación era tan indescifrable como su código, y no añadió nada. En retrospectiva, las revisiones de código habrían sido más útiles.

Usted (o un delegado) debería sentarse con este programador y recuperar parte de su código anterior. No es lo nuevo que sabe por solo trabajar en ello. Deberías pedirle que te guíe por su código con una interacción mínima. Esto también podría ser una sesión de "documentación" separada, en la que debe explicar por escrito su código. Entonces debería recibir comentarios sobre mejores enfoques.

Como nota aparte ... a veces se necesita cierta documentación, independientemente de lo buena que 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 de conocimiento de los programadores), y algunas cosas como las expresiones regulares deben documentar con qué se está comparando.

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

Algunos proyectos requieren que dicha documentación se incluya 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 código y esta tarea está integrada en la planificación del proyecto.

Voy a explicar a lo que se refieren la mayoría de las respuestas y comentarios: probablemente deba resolver el problema real aquí en lugar de tratar de impulsar la solución percibida.

Estás motivado para ver los comentarios en su código; ¿por qué ? Dio una razón; ¿Por qué es esa razón tan importante para ti? Él está más motivado para hacer otra cosa en su lugar; ¿por qué ? Él le dará una razón; ¿Por qué es esa razón tan importante para él? Repita esto hasta que llegue al nivel donde realmente surge el conflicto, y trate de encontrar una solución allí con la que ambos puedan vivir. Apuesto a que tiene muy poco que ver con los comentarios.

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 los métodos y los nombres de las variables deben describir su rol.

Mi TL me sugiere usar 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

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

Me encantan los comentarios, pero casi nunca los agrego al código en el primer paso. Tal vez sea solo mi estilo, pero voy a usar 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 cada vez que alguien me hace una pregunta sobre una sección del código, intento corregirlo para que tenga sentido.

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

Le sugiero que aliente a todos los miembros del grupo a "reconocer" que su código es legible para los demás. Esto significa que cada vez que alguien le haga una pregunta sobre su código, se compromete a hacer un cambio, o mejor aún emparejarse con esa persona para hacer el cambio correcto en ese momento!

Considera seriamente presionar por esto como parte de tu "Contrato de equipo" (y definitivamente crea un contrato si no tienes uno), de esa manera todos lo han acordado y lo tienes en una pared en alguna parte para que No hay ninguna pregunta sobre lo que has acordado hacer.

Quizás a este tipo se le deba dar una apreciación de la buena disciplina de codificación, y por qué es importante que otras personas puedan entender el código que está 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 variables eran tan malos, los comentarios eran tan malos o inexistentes, que la base de códigos dañaba mi productividad. No puedes trabajar para arreglar o mejorar una base de código que no entiendes, y si está escrito de forma impenetrable para los recién llegados, pasarán más tiempo tratando de entenderlo que trabajando en ello.

¡No hay mejor maestro que la dura experiencia!

Cada base de código tiene algunos fragmentos horribles al acecho, partes del sistema que nadie quiere tocar porque temen romper algo, o no pueden hacer ningún trabajo significativo porque el que escribió el código hace mucho que desapareció. Tomaron su comprensión del código con ellos. Si ese código no está comentado y no se documenta a sí mismo, entonces solo empeora las cosas.

Te sugiero que encuentres la parte de tu código base así, y le asignas a tu codificador problemático la responsabilidad. Dale la propiedad de él, hazlo bajo su responsabilidad, déjale 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 empezará a aparecer.

Dale un código de otra persona sin comentarios y pídele que entienda el código. Puede ser que él entienda la importancia de los comentarios apropiados entonces.

¿Este programador hace algún mantenimiento de código? Si no, él debería: verificar cualquier proyecto que no te guste y asignarle su mantenimiento.

Por lo general, esos son los proyectos mal documentados en los que pierdes horas tratando de comprender qué es lo que está haciendo para corregir lo que podría haber sido fácil de corregir. Si este tipo de experiencia no lo hace querer información actualizada, correcta y útil, nada lo hará.

En uno de mis proyectos anteriores faltaban docenas de comentarios (algoritmo, resultados o algún JavaDoc básico), así que decidí hacerle 130 problemas, notificaciones por correo electrónico sobre cada uno de los temas cada 4 días. Después de 3 semanas tuvo 280 problemas, luego decidió escribir comentarios.

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 debería eliminarse. Los comentarios inútiles que saturan 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. Están resaltados con texto blanco sobre un fondo verde. Los que realmente llaman tu atención.

Esto se debe a que el código explica lo que hace algo, y los comentarios son para 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: corte su método gigantesco en funciones nombradas 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 sea autoexplicativo y elimine el comentario.

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

Para complementar las respuestas aquí, podría agregar "Si quieres hacerlo bien, debes hacerlo tú mismo".

No me refiero a convertirme en "comentarista principal de código", me refiero a convertirme en un modelo a seguir para demostrar lo que le gustaría que hiciera este otro desarrollador. Dicen que mostrar es más efectivo que decir . 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 gusta hacer. Sin embargo, esas mismas tareas resultan ser las tareas "de la mascota" de mi esposa ... tareas que se deben hacer para que ella sea feliz. La misma situación se aplica viceversa. Creo que es posible que tenga que aceptar que este otro desarrollador tiene prioridades diferentes a las suyas, y no estará de acuerdo con usted en todo. La solución que mi esposa y yo hemos encontrado es que para esas tareas de "peeve mascota" solo tenemos que hacerlas nosotros mismos, incluso si eso significa trabajar un poco más por nuestra cuenta.

Simple: si el empleado no hace comentarios, dígale que presione shift+alt+j para comentarios automáticos en cada método simultáneamente con ingresar el código. Por favor haga la revisión del código para evitar estos problemas.