Comentarios en HTML y otros lenguajes – Buenas prácticas

¡Hola BitCucos! En éste tutorial os mostraré la forma correcta de escribir comentarios en HTML, Java, Shell Script, entre otros lenguajes de programación, así como algunos consejos de buenas prácticas en el uso de comentarios. Al tratarse de un tema simple y que no afecta en nada la funcionalidad del código, es de fácil comprensión para el lector.

Los comentarios HTML y en otros lenguajes de programación son segmentos de código utilizados para mostrar indicaciones cuya finalidad es facilitar la lectura y entendimiento del código, así que el contenido dentro de los comentarios realmente no es código, pero ayuda mucho a los desarrolladores y propietarios del producto a entender mejor cómo funciona el código e indicaciones especiales que los desarrolladores consideran anotar.

¿Cómo funcionan los comentarios en HTML y en otros lenguajes?

A través de unas marcas especiales, el compilador detecta que el código escrito allí no es funcional y es desechado al construir el código objeto. En el caso de lenguajes de programación interpretados, el traductor simplemente ignora la línea comentada.

Comentarios en HTML

Para crear comentarios en HTML seguimos la siguiente sintaxis:

<!-- 
Aquí va el comentario, en formato libre. Puede ser una línea o bloque.
-->

Adentro de los símbolos de inicio y final, se puede escribir cualquier cosa. Muy importante: Al ser un lenguaje de cliente, los comentarios en HTML se ven en el cliente (navegador), por lo tanto nunca ponga información sensible dentro de los comentarios en HTML, por ejemplo, su nombre y datos personales, nombres de usuario y contraseñas, etc. o las verá todo el mundo.

Comentarios en Java y Kotlin

En el lenguaje de programación Java existen los siguientes tipos de comentarios:

Comentarios de una línea en Java y Kotlin

Utilizan doble slash (no confundir con slash inverso)

// Éste es un comentario de una línea

Comentarios de varias líneas en Java y Kotlin

Utilizan la siguiente sintaxis:

/* 
Aquí va un comentario 
de bloque (también podría estar entre líneas, con los dos símbolos)
*/

Comentarios usados por Javadoc

Javadoc es una herramienta de Oracle utilizada para dar formato especial y estandarizado a los comentarios. Fácil de utilizar, éste tipo de comentarios son ideales para describir clases y métodos, ya que tienen la característica de leer algunas primitivas del código para resaltar ciertas partes importantes o ligadas por el código y lo convierte en una buena práctica de desarrollo.

Su sintaxis es la siguiente: (Favor de notar el doble asterisco)

/** 
 * Este es un comentario de Java con javadoc
 * Muy útil para describir clases y métodos
 */

Los comentarios de javadoc pueden contener primitivas que cambian de color al introducirlas en el código.

@param –> Primitiva utilizada para valores de entrada o parámetros.

@return –> Primitiva utilizada para valores de salida, enviados a través de return.

Un ejemplo con ésta clase en el lenguaje Kotlin es el siguiente:

/**
 * calculaSumaString - Calcula una suma de dos enteros desde string
 * @param num1 - Primer string (Número)
 * @param num2 - Segundo string (Número)
 * @return suma de los dos operandos (Int)
 */
fun calculaSumaString(num1: String, num2: String) : Int {
  val x = parseInt(num1)
  val y = parseInt(num2)
  if (x != null && y != null) {
    return x+y;
  }
  else {
    return 0;
  }
}

Comentarios en Python, Perl y Shell Script

En Python, Perl y Shell Script los comentarios se escriben iniciando con # (símbolo de número o gato), por ejemplo:

# Este es un comentario en Python y Perl

Comentarios en Ruby

Los comentarios en Ruby de línea son idénticos a los de Python y Perl, utilizando el símbolo #. Sin embargo, en los comentarios de bloque utilizamos el símbolo = tal y como se muestra a continuación:

=begin
Este es un comentario de bloque en Ruby
=end

Comentarios en Javascript, en C y C++

Los comentarios en Javascript, C y C++ son iguales a Java, salvo que no existen los comentarios leídos por javadoc. Es decir:

// Este es un comentario para una línea
/*
Este es un comentario de bloque, siempre hay que cerrarlo.
*/

Comentarios en SQL

Son los mismos que en Javascript, C y C++, añadiendo también el siguiente:

--Este es un comentario exclusivo de SQL

Nota, el comentario es de línea, se indica al inicio de la línea para evitar su ejecución.

Comentarios en PHP

Son válidos todos los comentarios de la sección de Javascript y Python, es decir

• // o #: Para líneas de comentarios
• /* Comentario */: Para bloques de comentarios

Etiquetas o Tags en los comentarios

Las etiquetas son segmentos mostrados dentro de los comentarios cuya finalidad es resaltar el texto para dar a entender al desarrollador algún mensaje especial o notificación dentro del código, son buenas prácticas de desarrollo y se sugiere eliminarlos antes de liberar el código fuente a un cliente o bien eliminarlos antes de integrar cambios vía git merge.

Las etiquetas más populares son las siguientes, aplican para javadoc y otros similares (pudiendo cambiar los términos).

• FIXME: Indica al desarrollador un código con problemas potenciales y que requiere revisión por para marcar código problemático potencial que requiere una atención especial y/o revisión.
• NOTE: Son anotaciones del desarrollador, generalmente informativas o de advertencias.
• TODO: Son actividades que faltan por desarrollar en esa sección de código.
• XXX: Muestra al desarrollador código equivocado o faltante, y también fallos en el código.

Notas adicionales

Los comentarios en html, java y otros lenguajes de programación, proporcionan una excelente forma de comunicación técnica entre los desarrolladores. Es concisa, ya que se dan instrucciones sobre el funcionamiento del código y se evita la deducción o prueba y error para saber cómo funciona el código.

En el caso de los Scrum master, los comentarios pueden aliviar la carga de muchos desarrolladores en desarrollos futuros, ya que en las empresas en donde rolan los desarrolladores de forma frecuente, se pierde mucho tiempo en las curvas de aprendizaje, tiempo que se podría reducir enormemente al mantener una documentación adecuada.

Adicionalmente, los comentarios bien definidos, así como el utilizar nombres de variables descriptivas, camel case, entre otros factores, facilitan a los arquitectos de software la revisión del código, así como su integración utilizando herramientas como TFS o Jira, herramientas que facilitan la gestión de código que analizaremos en otro momento.