Comentar código de forma "invisible"

Este tema tiene un origen histórico, trataré de empezar desde el principio ;-)

Cuando hace años empezamos en el mundo estático del "html" (cuando el 95% de los sitios solo eran puro html sin dinamismo, sin un lenguaje de scripting), lo que aprendimos fue a "programar html" haciendo muchas tablas (no usábamos los div's como ahora) y para seguir la "cascada" de código le agregábamos comentarios usando el tradicional <!-- -->

Por ejemplo:


Muy "cómodo" para hacer debug "manual" usando de apoyo los comentarios porque evidentemente era un "humano" el que debía controlar todo esto y se podía perder entre tanto código en cascada ;-)

Para los "técnicos" esto siempre fue desprolijo, ya que para nuestros futuros clientes o hasta curiosos, estábamos revelando detalles internos de nuestra aplicación / diseño. Está de más decir que no es para nada recomendable hacer comentarios técnicos importantes en ellos ya que es "código público" que cualquiera puede leer, y tampoco comentar código que no se va a usar, ya que es extremadamente desprolijo (si no lo quieres perder, respalda, o versiona).

Nota: no será la primera y última vez que veo en los comentarios de un código html insultos del propio desarrollador, que la verdad queda muy feo ;-)

Primer sugerencia, el código de producción debe estar "limpio", y si conoces algún sistema que pueda contener los comentarios en tu código de desarrollo e impida que quede en producción, úsalo.

Algunos ejemplos.

Usando el propio lenguaje de scripting: PHP

Cuando la tecnología evolucionó y empezamos a contar con lenguajes de scripting como PHP, la primera práctica que empezamos a adoptar fue el de embeber el código "dinámico" dentro de nuestro código html, pero dejamos todas las demás prácticas intactas, por lo que los comentarios seguían estando públicos en el html.

Con el tiempo, dejamos de "embeber" y ya no era tan evidente la manipulación del código html, empezamos a hacer invocaciones a funciones de tipo:

generarCabezalHtml();
generarContenido('Hola Mundo');
generarPie();


Por lo que ya no es el "humano" que debe seguir tan literalmente el código, ver si cierra o no, porque podemos validarlo a través de herramientas, y luego tratar de seguirlo a través del código PHP (aquí también ayudan mucho los IDEs en la pre-validación del código y evitar errores).

Una opción posible es mover todos los comentarios html al código php y estos quedan "privados" dentro del sistema.

Si esto no fuera suficiente, aún se podría generar algo como una configuración que diga "habilitarComentariosHtml" y que genere html con comentarios embebidos, y una vez en producción, eliminar esta opción (pero estaríamos generando mucho código poco productivo para el sistema).

Sigamos un siguiente nivel en la escala evolutiva ;-)

Usando sistemas de plantillas: Smarty

Con los años esto no nos quedó muy cómodo y preferimos optar por un sistema de "plantillas" (templates), y limpiar nuestro código PHP. Smarty fue una de las mejores opciones por años, lo cual te ofrecía además un código simil PHP del lado del template, pero podíamos volver a caer en la misma práctica, hacer comentarios html públicos.

Repitiendo lo que hablamos en el punto anterior, podíamos adoptar el mecanismo de comentarios de Smarty, lo cual genera el mismo efecto que hacerlo desde PHP. Se hacía con {* comentarios *}

{* display dropdown lists *}
<
select name="company">
{
html_options options=$vals selected=$selected_id}
select>


La diferencia con el primer caso de "solo html" es que lo estamos haciendo en la plantilla y no es público, y tampoco lo estamos haciendo del lado de PHP ya que toda la parte de generado de html era responsabilidad de Smarty (como una separación de capas).

Siguiendo con la evolución...

Nos pasamos a Zend Framework y usamos "Vistas"

Las vistas son como al principio de nuestra era, código html donde se embebe código PHP de la siguiente forma (un mix entre PHP embebido y sistema de plantillas).




Y volvemos al principio, he visto muchos proyectos que para poder hacer seguimiento de lo que generan de html tienen comentarios públicos html por todos lados, por lo que mi sugerencia final es... hagamos los comentarios dentro de la la vista, dentro del código PHP embebido y no dejemos expuestos nuestros comentarios internos.

Existen también herramientas que limpian el código, lo compactan y hasta te lo ofuscan, bien podrían ser una alternativa.

Pero la idea es esa, trata de no dejar comentarios que los pueda leer todo el mundo, sé ordenado y limpio. En lo personal cuando voy a ver páginas de diseño web que se ufanan de seguir "estándares", descubrir luego tablas o comentarios del tipo "abre tabla", "cierra tabla", etc, no me dejan muy tranquilo.

¿Qué opinas? ¿cuales son tus prácticas? ¿o no te importa que puedan descubrir leyendo el código de tu sitio? ;-)

10 comentarios:

victormc dijo...

La verdad que es bastante feo dejar comentarios de forma pública, aunque realmente un usuario sin conocimientos nunca los descubriría.
Tengo la costumbre de dejar los comentarios en las vistas, controllers, models.. siempre bajo PHP.
Por cierto, buen blog, soy nuevo por aquí ;)

Fran dijo...

Yo uso Zend Framework con Smarty (de hecho ellos recomiendan hacer ésto y te dan una clase para hacerlo sin complicarte) por lo que mis comentarios quedan en los templates..

enrique_place dijo...

Gracias por los comentarios Victor y Fran, me quedo tranquilo que hay desarrolladorse consientes de este tema (aunque uno observa un poco el código de muchos sitios y no dicen lo mismo ;-))

Fran, de paso aprovecho para preguntarte, las pruebas que yo hice con Smarty + Zend tenía el problema que tenía que trabajar los templates en otra estructura, en tu caso, lograste que se pudiera mantener el funcionamiento de la vista original y agregar funcionalidad de Smarty dentro de ella?

De todas formas, el uso de Hepers en las vistas tiende a sustituir la funcionalidad que te da Smarty.

GastoNike dijo...

Sinceramente yo soy de dejar comentarios en el XHTML del tipo:

< div id="content" >

< div id="example" >

Contenido de #example

< !-- end #example -- >
< /div >

Contenido de #content

< !-- end #content -- >
< /div >

Porque no le veo el problema, de hecho para los usuarios que quieren saber como está maquetado el sitio les es muy fácil leerlo porque no se pierden entre tanto div. Sin embargo creo que podría empezar a practicar lo de: "Con comentarios en desarrollo y sin comentarios en producción".

Saludos.

P.D: los espacios al principio y al final son para poder publicar el comentario.

José Zanni dijo...

En las Vistas yo pongo los comentarios dentro de etiquetas php. (Uso CodeIgniter)

Aunque en mi pasado recuerdo haber comentado a lo guarro dentro del HTML :D:D:D

Alfredo Alonso dijo...

No suelo programar mucho en PHP, pero los comentarios que hago están embebidos en PHP. A lo sumo, los comentarios que puedo dejar en HTML son como los que dice Gastón.

Tema aparte, se me ocurrió validar este blog en el http://validator.w3.org/ y contiene 568 errores y 295 advertencias.
Menos mal que sé que Enrique no es el encargado del desarrollo del sitio! ;-)

rorra dijo...

nunca vi un comentario que me permita explotar alguna vulnerabilidad de una pagina web... y creo que si alguien deja un comentario de como explotar una vulnerabilidad, entonces de seguro que hay otras vulnerabilidades mucho mas obvias

por otro lado, HTML en si es algo sucio, es decir, dificilmente encuentres una pagina que cumpla al 100% con los estandares de la W3C y ademas sea cross-browser...

a mi entender, lo importante no es el codigo HTML que se produce, si no como se ve la pagina... en cuanto a las vulnerabilidades, es mucho mas facil encontrar una vulnerabilidad XSS en un sitio con un hermoso codigo XHTML/CSS que encontrar una vulnerabilidad porque alguien dejo comentado en una vista como funcionan a nivel interno el sistema de rating

HK dijo...

Me parece que dejar comentarios en el código php es de gran ayuda , y mas cuando se trata de una aplicación web donde participan varios desarrolladores y se trata de garantizar escalabilidad y mantenimiento en el tiempo. Considero que documentar el html no es de gran ayuda ya que es un lenguaje de fácil lectura, es como leer el índice de un libro. Pero todo pude suceder, hace poco encontraron una vulnerabilidad en la apple store donde en el formulario del carrito de compras colocabas el id del iphone 3g, y listo!... Procesaban la orden por un iphone sin contrato de 700$ aprox.

Tincho dijo...

No suelo comentar el HTML porque en general es "bastante sencillo de seguir". Los comentarios los hago en el PHP y a veces en los JavaScript (dependiendo de la complejidad de los mismos). Creo que en esta última opción es donde quedamos "más expuestos" a vulnerabilidades o desprolijidades.

enrique_place dijo...

Que tal Alfredo ;-)

Sí, es horrible, blogger y sus templates son un asco, tienen errores por todos lados :-(

Generalmente todo proyecto que participo, una vez que la funcionalidad está "cerrada", empiezo a revisar todo con el validator de w3 hasta que quede al día.

Pero sí, también por salir apurado comete los errores de sacar algo sin revisar o hasta con "tablas", pero bueno, el producto está andando (obviamente que se me cae la cara de verguenza dejarlo así).

Estoy viendo cuando me puedo hacer un rato para migrar todo a wordpress :-)

PD: saludos a todos, leo atentamente todos los comentarios, pero no siempre puedo responder a cada uno.

Entradas populares