Los comentarios son líneas que existen en los programas informáticos y que los compiladores e intérpretes ignoran. Incluir comentarios en programas hace que el código sea más legible para los seres humanos, ya que proporciona información o explicaciones sobre lo que cada parte de un programa hace.
Según el propósito de su programa, los comentarios pueden servir como notas o recordatorios, o pueden estar escritos con la intención de que otros programadores puedan comprender lo que su código hace.
En general, es recomendable escribir comentarios mientras se escribe o se actualiza un programa, ya que se puede olvidar fácilmente el proceso de pensamiento y los comentarios que se introducen después pueden ser menos útiles a largo plazo.
Los comentarios de Go comienzan con un conjunto de barras diagonales (//
) y continúan hasta el final de la línea. Corresponde disponer de un espacio en blanco después del conjunto de barras diagonales.
Generalmente, los comentarios tendrán un aspecto similar a este:
Los comentarios no se ejecutan, por lo que no habrá indicaciones de comentarios al ejecutar un programa. Los comentarios se encuentran en el código fuente para que los seres humanos puedan leerlos, no para que las computadoras los ejecuten.
En un programa “¡Hello, World!”, un comentario puede tener el siguiente aspecto:
En un bucle for
que itera un segmento, los comentarios pueden verse así:
Los comentarios deberían hacerse en la misma sangría que el código al que se aplican. Es decir, una definición de función sin sangría tendría un comentario sin guión, y cada nivel de sangría siguiente tendría comentarios en línea con el código al que se aplican.
Por ejemplo, aquí se muestra la forma en que se comenta la función main
, con comentarios después de cada nivel de sangría del código:
Los comentarios se hacen para ayudar a los programadores, así se trate del programador original o de alguien que utilice el proyecto o colabore en él. Si los comentarios no pueden mantenerse ni actualizarse de forma adecuada con la base de código, es mejor no incluir un comentario en lugar de escribir uno que contradiga el código o pueda hacerlo en el futuro.
Al ingresar comentarios en el código, debería intentar dilucidar el por qué del código en lugar del qué o el cómo. A menos que el código sea particularmente complicado, con mirarlo generalmente basta para responder interrogantes como qué o cómo, razón por la cual los comentarios generalmente se centran en el por qué.
Los comentarios de bloque pueden utilizarse para explicar código más complicado o del que no espera conocimiento de parte del lector.
En Go, puede crear comentarios de bloques de dos formas. La primera consiste en usar un conjunto de dobles barras inclinadas y repetirlas para cada línea.
La segunda,en usar etiquetas de apertura (/*
) y etiquetas de cierre (*/
). Para documentar el código, se considera adecuado usar siempre sintaxis de //
. Sólo usarías la sintaxis /* ... */
para depuración, tema que abarcaremos más adelante en este artículo.
En este ejemplo, el comentario de bloque define lo que sucede en la función MustGet()
:
Es común ver comentarios de bloque al inicio de las funciones exportadas en Go: estos comentarios también son los que generan la documentación de su código. Los comentarios de bloque se utilizan también cuando las operaciones son menos sencillas y, por lo tanto, exigen una explicación completa. Salvo en el caso de la documentación de funciones, debería intentar evitar el exceso de comentarios sobre el código y confiar en la capacidad de otros programadores para comprender Go, a menos que escriba para un público en particular.
Los comentarios incorporados se producen en la misma línea de una instrucción, siguiendo el propio código. Al igual que otros comentarios, comienzan con una serie de barras diagonales. Una vez más, no es necesario incluir un espacio en blanco después de las barras, pero se considera apropiado hacerlo.
Generalmente, los comentarios incorporados tienen el siguiente aspecto:
Los comentarios en línea deberían utilizarse de forma racional, pero pueden ser eficaces para explicar partes complicadas o no obvias del código. También pueden ser útiles si cree que en el futuro es posible que no recuerde una línea del código que escribe, o bien si colabora con alguien que sepa que no esté familiarizado con todos los aspectos del código.
Por ejemplo, si no recurre mucho a la matemática en sus programas de Go, es posible que usted o sus colaboradores no sepan que con lo siguiente se crea un número complejo, por lo que posiblemente desee incluir un comentario incorporado sobre eso:
También puede usar comentarios en línea para explicar los motivos de una acción o proporcionar información adicional, como en el siguiente caso:
Debería usar comentarios en línea solo cuando sea necesario y cuando puedan proporcionar orientación útil para la persona que lea el programa.
Además de usar comentarios como una forma de documentar código, también puede usar etiquetas de apertura (/*
) y cierre (*/
) para crear un comentario de bloque. Esto le permite hacer comentarios sobre código que no desee ejecutar mientras pruebe o depure un programa en proceso de creación. Es decir, cuando experimente errores después de implementar nuevas líneas de código, es posible que quiera comentar algunas de ellas para ver si puede resolver el problema puntual.
Las etiquetas /*
y */
también pueden permitirle probar alternativas mientras determinan la manera de configurar su código. También puede usar comentarios de bloque para comentar código que produce errores mientras continúa trabajando en otras partes de su código.
Nota: Solo se deberían agregar comentarios al código para pruebas. No deje fragmentos de código con comentarios en la versión final de su programa.
Comentar código con las etiquetas /*
y */
puede permitirle probar diferentes métodos de programación, así como ayudarlo a encontrar el origen de un error comentando y ejecutando partes de un programa de forma sistemática.
El uso comentarios en sus programas de Go le permite hacer que estos últimos sean más legibles para los humanos, lo cual lo incluye a usted mismo en el futuro. Al añadir comentarios apropiados que sean pertinentes y útiles, puede hacer que resulte más sencillo para otros colaborar con usted en los proyectos de programación y hacer que el valor de su código sea más obvio.
Al comentar su código de forma adecuada en Go, también podrá usar la herramienta Godoc. Godoc es una herramienta que extraerá comentarios de su código y generará documentación para su programa de Go.
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
This textbox defaults to using Markdown to format your answer.
You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!