Cómo convencer a la gente para que comente su código [cerrado]

https://stackoverflow.com/questions/159597

03-07-2019
|

Pregunta

¿Cuáles son buenos argumentos para convencer a otros de que comenten su código?

Noto que muchos programadores prefieren la velocidad percibida de escribir código sin comentarios sobre dejar algo de documentación para ellos y para otros. Cuando trato de convencerlos, escucho cosas a medias como "el nombre del método / clase debería decir lo que hace". etc. ¿Qué les dirías para cambiar de opinión?

Si está en contra de comentar, simplemente deje comentarios. Esto debería ser un recurso para las personas que intentan convencer a las personas de comentar el código, no de otra manera. :-)

Otras preguntas relacionadas son: Código de comentarios , ¿Comenta su código y ¿Cómo le gustaría sus comentarios .

Solución

La mejor manera de convencer a una persona es hacer que se dé cuenta por sí misma. Haz que depuren código bien comentado. Les mostrará cómo son los buenos comentarios: los comentarios no sirven de nada a menos que realmente transmitan información relevante (que generalmente es el "por qué", porque el código describe el "qué"). Se darán cuenta de lo fácil que es. Luego déjelos volver a algunos de sus códigos antiguos. Se darán cuenta de lo difícil que es. No solo les ha mostrado qué no hacer, sino qué hacer (esto es más importante). No tienes que hacer más. Además, no tiene que intentar convencerlos verbalmente. Simplemente deben comprender la necesidad de comentar el código a su manera. Esto es, por supuesto, suponiendo que el código que necesita ser comentado no se explica por sí mismo.

Otros consejos

Solo comente el " por qué " y no el "qué". Hasta ahora estoy de acuerdo, debe quedar claro por la clase o método o nombre de la variable lo que hace y para qué se utiliza. Refactorice donde no lo hace en lugar de comentarlo.

Si adopta este enfoque, recibirá comentarios y recibirá comentarios útiles. A los programadores les gusta explicar por qué están haciendo algo.

Muéstreles su propio código de hace 6 meses. Si no pueden entender y describir exactamente lo que hace dentro de 2 a 4 minutos, su punto probablemente haya sido explicado.

Mi opinión:

No lo haría. El nombre del método / clase debe decir lo que hace. Si no es así, o el método o la clase está tratando de hacer demasiado, o se llama mal.

Soy fanático de comentar por qué, no qué. Si no está claro por qué el código está usando un enfoque sobre otro, coméntelo. Si tuvo que agregar una variable no utilizada de hack para evitar un error del compilador, comente por qué. Pero comentarios como '' // Conectarse a la base de datos '' son signos de mal código o malas políticas. Un método llamado ConnectToDatabase () es mucho mejor. Y si tiene " // Determine la IP del servidor de DB " en él, quizás eso debería extraerse a un método llamado " DetermineDbServerIPAddress () " ;.

El diseño puede documentarse, pero los comentarios son generalmente un lugar pobre para ese nivel de documentación. Con conocimiento del diseño y algunos comentarios sobre por qué, qué y cómo debería ser obvio. Si no es así, en lugar de convencerlos de que comenten su código, pídales que lo mejoren.

Quizás es algo que se debe aprender de la experiencia; específicamente, la experiencia de volver a su propio código después de seis meses, y tratar de averiguar qué demonios estaba pensando (o en qué estaba) cuando lo escribió. Eso ciertamente me convenció de que los comentarios no eran una mala idea.

Déles un poco (~ 500 líneas, mínimo) horrible, código de espagueti sin comentar para refactorizar. Asegúrese de que las variables no tengan un nombre lógico. Espacio en blanco opcional.

¡Y mira cómo les les gusta!

Demasiado duro, pero tiene dos puntos de una sola vez.

Escribe bien tu código.
Comenta para que y otros sepan lo que significa.

Debo enfatizar que este código no debería haberse originado a partir de ellos. Los comentarios son realmente útiles para comprender su propio código, meses después, pero también son casi esenciales para comprender partes complejas del código de otras personas . Deben comprender que alguien más podría tener que entender lo que están haciendo.

Una edición final: comentar calidad también es bastante importante. Algunos desarrolladores tienen una relación de código a comentario de casi 2: 1 en su trabajo, pero eso no los convierte en buenos comentarios. Puede tener sorprendentemente pocos comentarios en su código y aún así tener mucho sentido.

Explica lo que estás haciendo . Sin embargo, la calidad de su código debería hacer la mayor parte de este trabajo por usted.
¡Más importante, explique por qué está haciendo algo ! He visto tanto código que dice exactamente qué está haciendo algo sin una idea real de por qué el desarrollador (desafortunadamente yo la mayoría del tiempo) pensó que era una buena idea en primer lugar.

Recuérdeles que leer el código solo puede decirles lo que hace el código , no lo que se supone que debe hacer .

Si usted o los otros desarrolladores no han leído Code Complete (o Code Complete 2 ) aún así, detenga lo estás haciendo y léelo.

Una cosa que destaca es "Una función debe hacer una sola cosa y hacerlo bien". cuando dicha función lleva el nombre de la única cosa que hace bien, ¿qué otra necesidad hay para comentar?

Los comentarios tienen la costumbre de no estar sincronizados con el código que se supone que deben describir. El resultado puede ser peor que no tener el comentario original en primer lugar. No solo eso, sino que los desarrolladores saben que los comentarios pueden envejecer y no se puede confiar en ellos. Por lo tanto, ¡leerán el código y discernirán por sí mismos lo que realmente está haciendo de todos modos! Esto anula el punto de poner los comentarios allí en primer lugar.

Habiendo dicho que lo mismo puede ser cierto para el nombre de una función, puede haber sido nombrado originalmente, pero en el tiempo extra se le han agregado nuevas operaciones que no se mencionan en el nombre.

Todos los comentarios parecen separar las líneas de código que un desarrollador preferiría estar más cerca para poder ver más por pantalla completa. Conozco mi propia reacción a un fragmento de código con muchos comentarios que tengo que entender. Eliminar todos los comentarios. Ahí ahora puedo ver en qué consiste el código.

Al final del día, si va a pasar el tiempo haciendo las cosas bien , su tiempo se gastará mucho mejor refactorizando el código para garantizar que se describa tan razonablemente como sea posible en lugar de simplemente escribir comentarios Tal ejercicio vale la pena de otras maneras, como la identificación de fragmentos comunes de código.

Vale la pena tener en cuenta también que muchos buenos desarrolladores prefieren escribir C # limpio, nítido, Java, cualquiera que sean los lenguajes humanos mucho menos precisos con todas las suposiciones y ambigüedades que tienen. Es cierto que la mayoría de las personas con sentido común sabrían cuántos detalles son suficientes, pero los buenos desarrolladores no son 'la mayoría de las personas'. Es por eso que terminamos con comentarios como \\ agrega a a b y lo almacena en c (ok, eso es demasiado extremo, pero entiendes el punto).

Pedirles que hagan algo que odian hacer y que francamente no son muy buenos (incluso si estás convencido de que es lo correcto) es simplemente una batalla ya perdida.

No estoy siendo sarcástico contigo, pero deberías reformular la pregunta para que sea ¿Cómo convencer a otros desarrolladores para que trabajen en equipo?

En serio, algunas personas suponen que puedes leer su mente.

Si forma parte de un equipo ágil, el código es de propiedad colectiva, por lo que cuando vea un código no comentado, incómodo o difícil de leer, continúe y cámbielo (refactorícelo) para que lo entienda. Si la gente se queja, dígales por qué y sea sincero. Que lo encontraste incomprensible y que nadie posee el código.

Nuestra estrategia es tener revisiones sistemáticas del código y rechazar el código que no está debidamente documentado (a través de comentarios, denominación y organización de funciones adecuadas, etc.). Si no está claro para el revisor, vuelve al banco de trabajo, punto.

Diría que ayer tuve que leer parte de su código. Pude entenderlo, pero menos de o igual a 5 líneas de comentarios bien elegidas que explican cómo logró sus objetivos me habría permitido leerlo en aproximadamente una décima vez y luego podría haberme preocupado por entender un problema en su lugar. No soy estúpido, y tú no eres más inteligente porque puedes escribir cosas que son difíciles de entender. Por el contrario, si no puede producir documentación legible + conjuntos de código, entonces no es tan desarrollador.

Hace mucho tiempo que me perforaron: si escribes algo y alguien de habilidad razonable no puede entenderlo, entonces es tu culpa, no su culpa. Esto se aplica a la escritura en lenguajes naturales, y se aplica a la escritura en lenguajes de programación.

Ha habido discusiones similares sobre comentarios. Este es el de las reglas que las personas siguen al comentar el código: ¿Cuáles son sus "reglas duras"? sobre comentar tu código? . Algunas de las respuestas también tienen muy buenas razones por las que desea comentar su código.

Muestra sabiduría en tu deseo de comentarios, y será más probable que escuchen.

Menos es más.

Enfatice la calidad sobre la cantidad.

En mi equipo, hubo un impulso para comentar todo en ciertas API. Algunos desarrolladores comenzaron a utilizar una herramienta que generaría comentarios automáticamente al observar los nombres y las firmas de los métodos.

Por ejemplo:

/// <summary>
/// Gets the Person.
/// </summary>
/// <returns>
/// A Person
/// </returns>
public Person GetPerson()
{

}

¿Puedes pensar en un mayor desperdicio de espacio en pantalla? ¿Puedes pensar en una mayor pérdida de ciclos cerebrales que leer comentarios que no proporcionan información nueva?

Si es obvio por la firma del método, ¡no lo diga! Si puedo resolverlo en unos segundos, no lo ponga en un comentario. Como otros lo han dicho, dime por qué elegiste hacerlo de esa manera, no qué hiciste. Escriba su código para que sea obvio lo que hace.

Dirija con el ejemplo. Los desarrolladores se dejan influenciar fácilmente cuando ven The Right Thing, por lo que ver prácticas sólidas en acción puede alentarlos a hacer lo mismo. Además, puede alentar a su grupo a adoptar métricas de código que aborden el mantenimiento del código y los comentarios. Por ejemplo, Code Analysis producirá un error para los métodos sin documentación resumida.

Los estándares de codificación actuales en mi lugar de trabajo actual son comentar cada función. Las reglas en blanco como esta son dañinas y nunca deberían estar en su lugar. Hay situaciones (y algunas de ellas comunes) en las que agregar comentarios elimina la legibilidad.

class User {
    getUserName() { /* code here */ }
}

¿Cuál es el punto de agregar un encabezado de función a la parte de código anterior? ¿Qué más vas a decir besdies " obtiene el nombre de usuario " ;. No todo el código necesita ser comentado. Mi regla general es: omita los comentarios si no está agregando información útil que la firma de la función no.

Los comentarios deben ser exhaustivos, escritos a nivel de intención (por qué no cómo) y raros.

Cuando escribo código, tiendo a hacer comentarios bastante razonables de forma habitual. Luego, vuelvo y trato de eliminar tantos comentarios como sea posible, sin disminuir la comprensión del código. > 80% del tiempo, esto es tan fácil como extraer un método bien nombrado, esto generalmente resulta en un comentario que simplemente duplica la información en el código mismo. Más allá de eso, si hay una sección de código que '' necesita '' un comentario Busco formas de simplificarlo o hacerlo más claro.

El código debe autodocumentarse, y con las técnicas correctas usted puede llegar al 95% del camino con bastante facilidad. En general, considero que es un error si quedan comentarios sobre el código que revisé.

Depende de cuánto poder tengas ...

Descubrí que una forma muy efectiva era convertirlo en una parte fija de las revisiones de código basadas en pares: puntos para comentarios. Si hubiera un comentario de que el código estaba mal comentado, haría que el desarrollador lo comentara a mi satisfacción, lo que básicamente significaba que tenían que describir suficiente código para que yo lo entendiera imprimiéndolo y leyéndolo. Y yo también lo haría.

Sorprendentemente, esto fue popular entre los desarrolladores, aunque suene dickensiano. Dos cosas pasaron. Primero, la gente comenzó a comentar su código. En segundo lugar, el código mal comentado se convirtió en una señal de que el desarrollador no entendía lo que había escrito (de lo contrario, lo habría descrito).

El único inconveniente real fue que los comentarios tenían que mantenerse al día con el código cuando se revisó para corregir errores, etc. Esto era casi imposible de aplicar en una tienda de desarrollo real, pero una vez que se recogieron suficientes buenas prácticas, se ordenó de sucedió naturalmente.

Por cierto, prefiero los comentarios en el propio código en lugar de una novela de Dostoievski como una cadena de documentos. El primero es una ayuda útil para los programadores posteriores. Este último es solo un largo texto desactualizado que llena los documentos y engaña a todos.

Haga que usen una API desconocida, pero realice la programación en una máquina que no esté conectada a Internet (si puede encontrarlos en estos días) para que no tengan acceso a la documentación de la API. ¡Esto es efectivamente lo que están obligando a otros desarrolladores a hacer si están tratando de usar el código de los no documentadores!

También debe diferenciar dos comentarios diferentes aquí:

Comentarios de API (javadoc u otro tipo de documentación similar): puede solicitar que usan su propio código en un escenario de límite (condiciones límite como objetos nulos o cadenas vacías o ...) y ver si realmente logran recordar qué hacen sus propias funciones en esos casos
(Es por eso que estoy a favor de un javadoc completo, incluido el valor límite )
Comentarios internos (dentro del código fuente): puede pedirles que expliquen cualquier función que hayan codificado, simplemente elija una función con un realmente alto nivel de complejidad ciclomática , y verlos luchar alrededor de todos los diferentes flujos de trabajo de código y ramificación de decisiones;)

Bueno, siempre está el " si no comenta su código, encontraremos a alguien más que comentará el suyo " enfoque.

Más suavemente, dígales que están decepcionando mucho al equipo si no documentan y comentan lo que están haciendo. El código NO pertenece al individuo, a menos que sean lobos solitarios completos. Pertenece al equipo, al grupo, ya sea una empresa o una comunidad.

" Escribir código " = " Secuencia de escritura de comandos en un idioma especial " + " Escribir comentarios "

¡Será evidente comentar el código al escribirlo ! ¿Alguna vez ha comentado código que ya tiene 3 o 4 meses? (¡Por supuesto que sí, y fue todo menos diversión!)

Si su proyecto ya está bien documentado, los programadores que agregan un nuevo código pueden estar motivados para escribir comentarios de manera similar.

@James Curran ¡Estoy 100% de acuerdo! Puedo leer su código y averiguar qué le dijo al compilador que hiciera; pero eso no significa que fue su intención hacer que el compilador haga eso. Sé que no soy un programador lo suficientemente arrogante como para creer que cada vez que escribo código hace exactamente lo que estaba tratando de hacer. Además, a menudo encuentro que me ayuda a detectar errores lógicos tontos en mi código al revisarlos después de escribirlos e intentar explicar lo que pretendía que hiciera el código.

Una idea es señalar que lleva menos de un minuto escribir una o dos oraciones por clase y menos de medio minuto escribir una oración por método.

Dígales que documenten sus funciones e interfaces con los comentarios de Javadoc y luego que ejecuten el código a través de Doxygen para generar una documentación HTML atractiva para su código. El factor de frescura puede ser un buen motivador a veces.

Utilizo una técnica sutil:

Establezco el nivel de advertencias en el proyecto para que se informe como errores. Y nuestro servidor de integración continua está construyendo la solución completa junto con la documentación XML en cada entrada.

Si los desarrolladores no escriben los comentarios, ¡la compilación falla! Y después de eso, tienen que escribir los comentarios, así que después de un tiempo, se acostumbraron.

No es agresivo en términos de presión, pero me parece una buena manera de corregir su comportamiento.

Si los desarrolladores tienen que participar en las revisiones de código y están expuestos a buenos comentarios, deberían poder obtener la pista. Si no consideran que la práctica sea útil, deberían recibir comentarios de sus revisores expertos.

Si no lo hace (suponiendo que usted sea el supervisor / gerente), lo hará parte de su evaluación del desempeño. Si puede medirlo, puede evaluarlo en base a él.

Asegúrese de que sea un comentario REVISADO en el que puntúe, ya que los desarrolladores pasivo-agresivos documentarán cada última declaración como una FU no tan sutil.

Me he convertido en un firme creyente de lo que yo llamo Headrick's Rule , llamado así por un compañero de trabajo mío que descubrió que una buena manera de motivar a alguien a hacer algo es hacer que sea doloroso para ellos < em> no para hacerlo.

En su caso, solicite a sus desarrolladores que no comentan que pasen una o dos horas explicando su código, tal vez a una "lenta". audiencia, tal vez durante la hora del almuerzo "para evitar el deslizamiento del proyecto" recorrerá un largo camino. ¡Las personas inteligentes, incluso las tercas, aprenden rápido!

En mi opinión (y estoy hablando de programación .Net aquí) si tiene que poner un comentario, ha fallado en hacer que el código sea legible. ¡La respuesta suele ser refactorizada!

Sin embargo, si siente que tiene que poner un comentario, siempre debe ser un " por qué " tipo de comentario y no un comentario que explique lo que hace el código.

Escribir lo que hará un método / clase antes de codificarlo realmente ayuda mucho a hacerlo bien, y lo ha comentado.

Solo emplee buenos ingenieros que se aseguren de que su código implícitamente establezca la intención (utilizando comentarios y otros). Cualquiera que quiera un trabajo tendrá que hacerlo bien. Duro, pero justo, en mi humilde opinión.

Licenciado bajo: CC-BY-SA con atribución

No afiliado a StackOverflow