La mejor manera de comentar su código

Ningún programador quiere convertir un código simple en un códice maya, pero muy a menudo terminamos produciendo código que, años después, se lee como jeroglíficos.

¿Qué pasa cuando se trata del código real? ¿Diálogos concisos? ¿Descripciones de párrafos largos? ¿Cuánto es suficiente y cuándo es demasiado?

Cómo comentar el código es un tema perenne de debate para los programadores, uno al que se lanzó recientemente el desarrollador Zachary Voase , argumentando que una de las posibles fallas con los comentarios extensos (o cualquier comentario en realidad) es que parece que nunca se actualizan cuando cambia el código. . "Olvidamos", escribe Voase, "pasar por alto un comentario al cambiar el comportamiento fundamental de la semántica del código al que se relaciona".

Voase cree que la solución está en nuestros editores de texto, que normalmente "desactivan" los comentarios y luego se desvanecen en segundo plano para que podamos centrarnos en el código real. Él cree que deberíamos hacer lo contrario: hacer que los comentarios destaquen. Mirar los ejemplos visuales en la publicación de Voase hace que el argumento sea un poco más convincente. Los buenos editores de texto tienen esquemas de color configurables, por lo que no debería ser demasiado difícil intentarlo y ver si mejora sus comentarios y su código.

La mejor manera de comentar su código depende de usted, pero cualquiera que sea el camino que su equipo decida seguir, el mejor consejo es asegurarse de tomarse el tiempo para tener un plan para los comentarios. Los comentarios más inútiles están escritos al azar, lo que también hace que sea poco probable que se actualicen cuando cambie el código. Hay tantos enfoques como programadores; solo asegúrate de decidirte por uno y apégate a él. En el futuro, cuando sea el momento de actualizar ese código anterior, lo agradecerá.