Al programar y escribir código, debemos recordar que antes que todo estamos escribiendo en un lenguaje de programación para facilitar la lectura a otros humanos. Si bien la sintaxis de un lenguaje puede ser muy amigable por si sola, una buena práctica es agregar comentarios que puedan aportar más al entendimiento del problema que se resuelve.
A medida de que los programas que escribimos se vuelven más grandes, agregar comentarios puede resultar de gran ayuda a los programadores que se acercan por primera vez a esta base de código, pero es necesario tomar en cuenta algunas recomendaciones para limitar su función como una ayuda en casos donde consideremos que sea necesario y evitar llenar el código con comentarios para cada comportamiento reflejando un severo caso de comentaritis aguda.
Agrega comentarios sólo cuando sea necesario
Siempre debemos tomar en cuenta que el código debería hablar por si mismo, por ejemplo, no deberías agregar un comentario para indicar el contexto de una variable o de una función. En medida de los posible, los comentarios deben evitar ser innecesarios como por ejemplo explicar un comportamiento que dentro del contexto resulta obvio.
Agregando buenos comentarios
Para que tus comentarios sean efectivos, debes escribirlos de manera que puedan ser entendibles por cualquier persona. Un buen comentario debería responder a la pregunta ¿porqué? en lugar de responder a la pregunta ¿qué?. También es importante mantenerlos actualizados, puesto que al modificar una rutina o variable y no actualizar el comentario asociado podríamos caer en una contradicción que volvería confuso a tu código.
Comentar tu código siempre es una buena práctica para agregar legibilidad y hacer más entendible lo que estás tratando de resolver. Existe una línea que separa el código sobre-comentado del código poco-comentado. A medida que se vaya adquiriendo experiencia escribiendo más programas, se aprende a conocer cuándo resulta efectivo y cuándo no el agregar comentarios.
Referencias:
PEP 8 — the Style Guide for Python Code - Comments
