En http://www.stickyminds.com/testandevaluation.asp?Function=edetail&ObjectType=ART&ObjectId=9041&tth=DYN&tt=siteemail&iDyn=3 dice que muchas veces sobra el comentario de nuestro código o, como mínimo, que si el código está bien hecho, debería sobrar.
La idea es que un código bien hecho debe ser autoexplicativo. Si el código es lo suficientemente autoexplicativo, el comentario es redundante y, por tanto, es algo que sobra. Además, necesita mantenimiento y que en algún momento puede decir lo contrario que el código. Por ejemplo, si modificamos el código y nos olvidamos de cambiar el comentario.
La idea, por ejemplo, es que si tenemos lo siguiente
// muestra una tabla con todos los usuarios
visualizaTabla()
deberíamos cambiar el nombre del método por este otro
// Comentario inútil: muestra una tabla con todos los usuarios
muestraTablaDeTodosLosUsuarios();
Así el comentario puesto es totalmente inútil y no es necesario.
Según se comenta en el artículo, es buena idea rehacer el código, haciendo que los nombres de los métodos se parezcan lo más posible a los comentarios que hemos puesto previamente, para de esta forma evitar poner comentarios y que el código se pueda leer fácilmente y entenderse mejor.
En el artículo sólo excusa poner comentarios cuando todo esto falla. Pone cuatro ejemplos concretos en los que sí se pueden poner comentarios:
- Un comentario al principio de cada clase para explicar para qué sirve esa clase en el sistema
- Explicar limitaciones del código o cosas que se presuponen al hacerlo. En general, cosas que en el código no están reflejadas.
- Advertencias sobre el código, del estilo de que el código necesita mejorarse en tal punto o que no es lo suficientemente robusto, etc, etc.
- Cuando se usen algoritmos conocidos, indicar dónde puede encontrarse dicho algoritmo, vaya, lo que se conoce como bibliografía. En qué libro o página de internet está explicado dicho algoritmo.
No hay comentarios:
Publicar un comentario