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? ;-)