Sin comentarios!!!

Maldita sea la hora en que decidieron bombardearnos con aquello de... "¡escribe comentarios en el código!". El código bien escrito no necesita comentarios!!!. Un comentario significa que el código no es suficientemente expresivo como para ser leído y mantenido sin comentarios. Cuando sientas la necesidad de añadir un comentario, plantéate reescribir el código primero. No escribas comentarios porque sí. Los comentarios requieren mantenimiento. Si modificas el código y no actualizas sus comentarios, entonces es todavia peor!!!. Los comentarios hay que evitarlos todo lo posible.
Si se trata de un complejo algoritmo matemático, la documentación puede ser un link a un documento científico que lo explica.
Ya lo saben, los comentarios son dañinos, ¡no comentes tu código! ¡hazlo autoexplicativo!

Dedicado a mi buen amigo Adrián 🙂

Enjoyed reading this post?
Subscribe to the RSS feed and have all new posts delivered straight to you.
  • http://elbruno.com/ El Bruno

    Jeje, supongo que detrás de esto existirá una situación que desconozco, pero sino simplemente comentarte que los extremos son muy malos y; el “zero comment” es bastante pero bastante peligroso 😀

    pero claro, es solo una opinión personal

    Saludos

  • http://carlosble.com Carlos Ble

    Gracias por tu comentario Bruno y felicidades por tu blog, es muy conocido 🙂

    Tienes razón, los extremos son muy malos. En el caso que me llevó a escribir esto, realmente no se pueden escribir 0 comentarios, puesto que la aplicación no dispone de NINGUN test autómatico, ni unitario, ni de integración, ni nada. Terrible.
    El “zero comment” se puede aplicar desde mi punto de vista cuando se aplica Test Driven Development todo el tiempo, ya que la API queda perfectamente documentada con código. Si se hace pair programming y se hacen revisiones de código adecuadamente, entonces el riesgo de que haya código que necesite documentación, se minimiza.
    Lógicamente si el desarrollador es junior, no tiene ayuda ni supervisión, y no escribe ni un sólo test, el zero comment seguramente será malo. No obstante, siempre será mejor el zero comment, que añadir una línea de comentario encima de cada variable que se define, para explicar qué se va a hacer con esa variable. Este caso es el que estaba viendo en el código de un compañero y en el de muchos otros, en un proyecto al que me he incorporado hace poco.
    La gente tiende a pensar que por el hecho haber añadido líneas de comentario ya ha escrito un buen código. Nada más lejos de la realidad.

    Saludos cordiales 🙂

  • http://jmbeas.blogspot.com Jose M Beas

    Totalmente de acuerdo con Carlos. Por cierto, me atrevo a recomendar que os leáis el capítulo que dedica Robert C. Martin a este tema en su “Clean Code”.

  • http://agilizar.es Juan

    Hola Carlos.

    Un tema recurrente el de los comentarios.
    Hace no mucho tiempo JMB (el señor de más arriba con el que siempre es un placer charlar y discutir) y yo tuvimos la misma discusión (http://jmbeas.blogspot.com/2009/02/los-comentarios-en-el-codigo-son-basura.html)
    Yo soy de la opinión de “El Bruno” y veo muy peligroso irse a este extremo (lo mismo si fuera el contrario) y tomarlo como una religión (http://agilizar.es/blog/24/10/2008/comentarios-en-una-refactorizacion-perfecta/). Vamos, que ni tanto ni tan calvo.
    Es indudable que si el código es claro, ha sido apropiadamente refactorizado, los nombre de las variables, métodos, funciones, clases, etc. son auto-explicativos y, además, el código está cubierto por pruebas unitarias, los comentarios necesarios serán mínimos y quizá en algunos casos innecesarios. Pero de ahí a decir que los comentarios son dañinos, hay mucho trecho.
    En resumen, estoy de acuerdo que hay que evitarlos lo máximo posible y hacer todo lo posible para que el código sea claro por sí mismo y con ayuda de las pruebas unitarias. Sin embargo, no escribir absolutamente ninguno “porque sí” me parece excesivo y contraproducente.
    Como en muchas otras cosas creo que hay que usar el sentido común.

  • http://carlosble.com Carlos Ble

    Gracias Juan Y JM.
    Como dice mi abuelo, el sentido común es el menos común de los sentidos.
    Estoy de acuerdo en que las cosas no se deben hacer porque sí. Hay que razonarlas.
    Pero yo no he querido decir eso, y pienso que JM tampoco. Creo que el discurso es el mismo que el tuyo Juan.

    Saludos cordiales

  • http://www.fitnessmodels.info top fitness models

    Decent post. My partner and i won’t concur through everything, but you include numerous important opinions.

  • http://eforexloginnews.info Tommy Hukill

    fantastic post, very informative. I wonder why the other experts of this sector do not notice this. You must continue your writing. I am sure, you have a huge readers’ base already!

  • http://www.youtube.com/ Marine Augustus

    Good write-up, I am regular visitor of one’s blog, maintain up the excellent operate, and It’s going to be a regular visitor for a long time. Goldstar Locksmith 9620 w russell rd #2134 las vegas NV 89148 United States 702-475-6826.