Al ayudar a sus desarrolladores a comprender mejor cómo comentar su código, garantiza una mejor colaboración.
El acto de desarrollar software es un desafío en todos los frentes. La tarea de programar no sólo suele estar plagada de obstáculos cuando uno se enfrenta a trabajar en el código de otra persona que no utiliza comentarios, sino que ese trabajo también se vuelve exponencialmente más difícil.
Piénselo de esta manera: imagine que le dan todos los ingredientes para hacer pan, pero ninguna receta. Sabes que los ingredientes secos van juntos, pero es posible que no sepas las cantidades de cada uno. Lo mismo ocurre con los comentarios de código que pueden ayudar a servir como una especie de resumen de cómo un programador usó una función o cómo se cambió algo para abordar un desafío particular.
Los comentarios de código son esenciales para una programación eficiente y efectiva. Joel Spolsky (cocreador de StackOverflow) dijo una vez: "Es más difícil leer código que escribirlo". ¿Por qué es esto tan cierto? Parte de la razón son las malas críticas. Cuando los desarrolladores no comentan sobre su código, resulta casi imposible descifrar lo que está pasando. Pero con un script de comentarios sólido, este miasma de código es mucho más fácil de entender.
Entonces, para aquellos que buscan ayudar a sus desarrolladores a mejorar su trabajo, ¿qué hacer y qué no hacer al comentar código? Vamos a ver.
Utilice los comentarios como forma de comunicación.
Una de las mejores cosas que puede ayudar a comprender a sus programadores es que deben utilizar los comentarios como medio para comunicar sus intenciones y acciones a otros programadores. Si un programador incluye comentarios bien escritos en su código, está comunicando con todos sus colaboradores lo que está pasando en su trabajo.
Escribe comentarios pensando en otra persona.
En la misma línea, sus desarrolladores deberían considerar que los comentarios deben escribirse pensando en otras personas. Esta herramienta no sirve sólo para dejar notas sobre tu trabajo, sino también para ayudar a otras personas a descifrar lo que hicieron.
Uno de los principales propósitos de los comentarios es ayudar a otros programadores a comprender lo que sucede en el código. Esto significa que sus desarrolladores deben escribir de tal manera que cualquier desarrollador pueda abrir su trabajo y comprender lo que está sucediendo.
Trabajar para eliminar la confusión.
Los comentarios de código deben servir para eliminar el desorden de código. No se trata de mostrar tu trabajo, sino de simplificar el proceso de colaboración y entendimiento. Hacer que su trabajo sea claro y obvio debería ser el objetivo número uno de los comentarios de código.
Esto también significa que los comentarios de su desarrollador también deben ser muy claros y concisos (y no agregar aún más confusión a la mezcla).
Proporcionar enlaces a la fuente original del código copiado.
Si sus desarrolladores copian código de otras fuentes, siempre deben dejar enlaces a las fuentes originales. ¿Por qué? Porque quien siga tus pasos puede necesitar entender por qué usaste ese fragmento de código y cuál era tu intención original, e incluso puede necesitar contactar al desarrollador del código copiado.
Agregar comentarios al corregir errores
Los comentarios de código no son sólo para el código original (o copiado), sino también para cuando los desarrolladores corrigen errores. Estos comentarios deben explicar qué hicieron para corregir el error y por qué era necesario. Sin embargo, nuevamente, sus desarrolladores no deben escribir instrucciones extensas en los comentarios, sino que deben ser precisos y eficientes en sus palabras.
Utilice anotaciones o etiquetas de código.
Para ayudar a que las cosas sean concisas, sus desarrolladores deben utilizar etiquetas y anotaciones de código. Por ejemplo, @desc será una descripción, @param será una descripción de parámetro, @returns describirá la salida devuelta y @throws describirá posibles tipos de error. La mayoría de los desarrolladores deberían tener un conocimiento sólido de estas anotaciones y etiquetas. Si no, asegúrese de que aprendan sobre ellos.
Escribe comentarios al escribir tu código.
En lugar de que sus desarrolladores regresen después de completar el código para insertar comentarios, deberían escribirlos sobre la marcha. Esto puede evitar muchos problemas. En primer lugar, evitará que el desarrollador olvide por qué hizo algo. En segundo lugar, si algo le sucede a un desarrollador a mitad del proyecto, los comentarios ya estarán allí, por lo que alguien puede continuar donde lo dejó sin demasiados problemas.
no comentes de todo
También es importante que tus desarrolladores comprendan que no deben comentar todo. Los desarrolladores no deberían comentar sobre lo obvio. Este error les ocurre mucho a los nuevos programadores que sienten que necesitan documentar todo lo que crean a lo largo del camino.
Para ayudar con esto, pida a sus desarrolladores que consideren si lo que están escribiendo sigue convenciones y sintaxis ampliamente aceptadas, lo que significa que probablemente no necesite comentarios.
No utilice comentarios como sustituto de la documentación.
Los comentarios de código y la documentación no son lo mismo. No desea que los desarrolladores utilicen comentarios como documentación porque el código puede terminar siendo demasiado largo (y confuso) y generar trabajo innecesario. Esto sucede a menudo porque los desarrolladores odian escribir documentación.
Los comentarios de código existen para explicar funciones y enfoques específicos, no para describir cómo funciona algo en detalle. Si sus desarrolladores agregan información superflua en los comentarios de su código, debe detener este comportamiento antes de que se salga de control.
No hagas referencia a otros comentarios en tus comentarios.
Si sus desarrolladores hacen referencia a otros comentarios (o incluso a otros documentos), les están dando a otros desarrolladores más trabajo del necesario. Considere lo siguiente: un desarrollador coloca un comentario en un código que hace referencia a otro comentario. Esto significa que un desarrollador que siga a esta persona tendrá que buscar en el código para encontrar el comentario mencionado. Eso es mucho trabajo.
En lugar de hacer referencia a otro comentario, su desarrollador debe explicar lo que necesita decir (y hacerlo de manera eficiente). El objetivo debería ser dar a los demás menos trabajo, no más.
Conclusión
Los comentarios del código son tan importantes como el código real porque ayudan a facilitar el trabajo de todos. Si puede inculcar buenos hábitos de comentarios a sus desarrolladores desde el principio, puede estar seguro de que cualquiera puede tomar el código de otro desarrollador y saber exactamente qué se hizo, por qué se hizo y cómo se hizo.
