documentation - vender - Cómo convencer a las personas para que comenten su código

que decir para vender un producto (30)

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

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

Si no está de acuerdo, simplemente deje comentarios. Esto debería ser un recurso para las personas que intentan convencer a las personas de que comenten el código, de lo contrario. :-)

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

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

¡Será evidente para comentar el código mientras lo escribe ! ¿Alguna vez ha comentado un código que ya tiene 3 o 4 meses de antigüedad? (Por supuesto que sí, ¡y fue todo lo demás, pero divertido!)

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

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

Bueno, siempre está el enfoque "si no comentas tu código, encontraremos a alguien más que haga un comentario sobre ellos".

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

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

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

¡Y mira cómo les gusta!

Muy duro, pero gana dos puntos de una sola vez.

Escribe bien tu código.
Coméntelo para que usted y otros sepan lo que significa.

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

Una edición final: la calidad de los comentarios también es bastante importante. Algunos desarrolladores tienen una proporció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í tiene mucho sentido.

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

Depende de cuánto poder tienes ...

Encontré una manera muy efectiva de convertirlo en una parte fija de las revisiones de código basadas en pares: puntos para comentarios. Si hubo una observación de que el código fue mal comentado, haría que el desarrollador lo comentara a mi satisfacción, lo que básicamente significa que tenían que describir lo suficiente del código para que yo lo entienda al imprimirlo y leerlo. Y yo también lo haría.

Sorprendentemente, esto fue popular entre los desarrolladores, aunque suena 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 exactamente lo que habían escrito (de lo contrario lo hubieran descrito).

El único inconveniente real era que los comentarios tenían que mantenerse junto 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 implantaron las buenas prácticas, sucedió de manera natural .

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

Escribir lo que hará un método / clase antes de codificarlo realmente ayuda a hacer las cosas bien, y usted lo ha comentado.

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

Cuando escribo el código, suelo hacer un comentario bastante extenso como una cuestión de rutina. Luego, vuelvo y trato de eliminar la mayor cantidad posible de comentarios, sin disminuir la comprensibilidad del código. > 80% de las veces esto es tan fácil como extraer un método bien llamado, 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 ser autodocumentado, y con las técnicas correctas puede obtener el 95% del camino allí con bastante facilidad. En general, considero que es un error si quedan comentarios en el código que ingresé.

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

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

¿Cuál es el sentido de agregar un encabezado de función a la porción 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 ninguna información útil que la firma de la función no.

Mi opinión:

Yo no lo haría El método / nombre de clase debe decir lo que hace. Si no es así, o el método o la clase está tratando de hacer demasiado, o tiene un nombre pobre.

Soy fanático de comentar por qué, no qué. Si no está claro por qué el código usa un enfoque sobre otro, coméntelo. Si tuviera que agregar una variable no utilizada para solucionar un error del compilador, coméntele por qué. Pero los comentarios como "// Connect to database" son signos de código incorrecto o malas políticas. Un método llamado ConnectToDatabase () es mucho mejor. Y si tiene "// Determinar IP de servidor de base de datos" en él, tal vez eso debería ser extraído 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 el conocimiento del diseño y algunos comentarios sobre por qué, el qué y cómo debería ser obvio. Si no es así, en lugar de convencerlos para que comenten su código, haz que lo mejoren.

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

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

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

Si eres parte de un equipo ágil, el código es de propiedad colectiva, por lo tanto, cuando veas un código sin comentarios, torpe o difícil de leer, adelante y cámbialo (refactor) para que lo entiendas. Si la gente se queja, dígales por qué y sea sincero. Que lo encuentras incomprensible, y nadie posee el código.

Nuestra estrategia es tener revisiones de código sistemáticas y rechazar 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, regresa al banco de trabajo, punto.

Pídales que utilicen una API desconocida, pero programe 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 obligan a otros desarrolladores a hacer si intentan usar el código de los no documentadores!

Predicar con el ejemplo. Los desarrolladores se dejan influir fácilmente cuando ven Lo correcto, por lo que ver prácticas sólidas en acción puede alentarlos a hacer lo mismo. Además, podría 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.

Quizás es solo algo que debe aprenderse de la experiencia; específicamente, la experiencia de volver a su propio código después de seis meses, e intentar 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.

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 ), entonces detenga lo que está haciendo y léalo.

Una cosa que se destaca es "Una función debería hacer una sola cosa y hacerlo bien". cuando tal función recibe su nombre después de una cosa que hace bien, ¿qué otra necesidad existe para hacer un comentario?

Los comentarios tienen la costumbre de no sincronizarse con el código que se supone 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 qué 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 un nombre de función, puede haber sido bien llamado original, pero se le han agregado nuevas operaciones que no están aludidas en el nombre.

Todos los comentarios parecen separar las líneas de código que un desarrollador preferiría estar más cerca para que puedan ver más por pantalla completa. Sé mi propia reacción a un fragmento de código con muchos comentarios que debo entender. Eliminar todos los comentarios. Ahora puedo ver lo que el código está haciendo.

Al final del día, si vas a dedicar un tiempo a hacer las cosas bien, es mucho mejor dedicarlo a la refacturación del código para garantizar que sea tan autodescriptivo como sea posible en lugar de simplemente escribir comentarios. Tal ejercicio vale la pena de otras maneras, como la identificación de trozos comunes de código.

Vale la pena tener en cuenta también que muchos buenos desarrolladores prefieren mucho escribir C # limpio, Java, lo que sea que 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ía con cuánto detalle hay detalles suficientes, pero los buenos desarrolladores no son "la mayoría de la gente". Es por eso que terminamos con comentarios como //adds a to b and store it in 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.

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

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

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

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

Yo diría que "ayer tuve que leer parte de tu código. Pude entenderlo, pero menos de o igual a 5 líneas de comentarios bien escogidas que explicaban cómo lograba sus objetivos me hubieran permitido leerlo en aproximadamente un - a la vez y entonces podría haberme preocupado por entender un problema. No soy estúpido, y no eres más listo porque puedes escribir cosas que son difíciles de entender. Por el contrario, si no puedes producir conjuntos de documentación + código legibles, entonces eres menos desarrollador ".

Hace mucho tiempo que me enseñaron esto: si escribes algo y alguien de capacidad razonable no puede entenderlo, es tu culpa, no su culpa. Esto se aplica a la escritura en idiomas naturales, y se aplica a la escritura en lenguajes de programación.

Yo uso una técnica sutil:

Establecí el nivel de advertencias en el proyecto para informar como errores. Y nuestro servidor de Integración Continua está construyendo la solución completa junto con la documentación XML en cada ckeck-in.

Si los desarrolladores no escriben los comentarios, ¡falla la compilación! 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.

Demuestre sabiduría en su deseo de comentarios, y será más probable que los escuche.

Menos es más.

Enfatiza la calidad sobre la cantidad.

En mi equipo, hubo un impulso para comentar todo en ciertas API. Algunos desarrolladores comenzaron a usar una herramienta que generaría automáticamente comentarios mirando 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 propiedades inmobiliarias en pantalla? ¿Puedes pensar en un mayor desperdicio de ciclos cerebrales que leer comentarios que no brindan información nueva?

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

Si los desarrolladores tienen que participar en las revisiones de los códigos y están expuestos a buenos comentarios, deberían ser capaces de obtener la pista. Si no ven la práctica como útil, entonces deberían recibir algún comentario de sus colegas revisores.

Si no lo hace (suponiendo que sea el supervisor / gerente) hágalo parte de su evaluación de desempeño. Si puede medirlo, puede evaluar en función de ello.

Asegúrate de que sea un comentario REVISADO que puntúas, ya que los desarrolladores pasivo-agresivos documentarán cada declaración como FU no tan sutil.

Me he convertido en un firme creyente en lo que llamo la Regla de Headrick , nombrada así por un compañero de trabajo que descubrió que una buena forma de motivar a alguien para hacer algo es hacer que les resulte doloroso no hacerlo.

En su caso, pedirle a los desarrolladores que no comentan que pasen una o dos horas explicando su código, tal vez a una audiencia "lenta", quizás durante la hora del almuerzo "para evitar el deslizamiento del proyecto", será muy útil. Las personas inteligentes, incluso las obstinadas, aprenden rápido.

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

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

La mejor manera de convencer a una persona es hacer que se den cuenta por sí mismas. Haga que depuren bien el código 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, permítanles volver a algunos de sus códigos anteriores. 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 nada más. Además, no tienes que intentar convencerlos verbalmente. Simplemente deben entender la necesidad de comentar el código a su manera. Esto es, por supuesto, asumiendo que el código que necesita ser comentado no se explica por sí mismo.

Ha habido discusiones similares sobre los comentarios. Aquí está el de las reglas que las personas siguen al comentar el código: ¿Cuáles son sus "reglas duras" al comentar su código? . Algunas de las respuestas también tienen muy buenas razones por las cuales desearía comentar su código.

También debe diferenciar dos comentarios diferentes aquí:

Comentarios de la API (javadoc u otro tipo similar de documentación): puede pedirles que usen su propio código en un escenario límite (condiciones de contorno como objetos nulos o cadenas vacías o ...) y ver si realmente logran recordar qué hace sus propias funciones en esos casos
(Es por eso que estoy a favor de un javadoc completo que incluye 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 nivel de complejidad ciclomática realmente alto , y vea cómo luchan con todos los diferentes flujos de trabajo de código y la derivación de decisión;)