Cómo escribir comentarios en Go

Introducción

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.

Sintaxis de los comentarios

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:

// This is a comment

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:

package main

import (
	"fmt"
)

func main() {
	// Print “Hello, World!” to console
	fmt.Println("Hello, World!")
}

En un bucle for que itera un segmento, los comentarios pueden verse así:

package main

import (
	"fmt"
)

func main() {
	// Define sharks variable as a slice of strings
	sharks := []string{"hammerhead", "great white", "dogfish", "frilled", "bullhead", "requiem"}

	// For loop that iterates over sharks list and prints each string item
	for _, shark := range sharks {
		fmt.Println(shark)
	}
}

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:

package main

import "fmt"

const favColor string = "blue"

func main() {
	var guess string
	// Create an input loop
	for {
		// Ask the user to guess my favorite color
		fmt.Println("Guess my favorite color:")
		// Try to read a line of input from the user. Print out the error 0
		if _, err := fmt.Scanln(&guess); err != nil {
			fmt.Printf("%s\n", err)
			return
		}
		// Did they guess the correct color?
		if favColor == guess {
			// They guessed it!
			fmt.Printf("%q is my favorite color!\n", favColor)
			return
		}
		// Wrong! Have them guess again.
		fmt.Printf("Sorry, %q is not my favorite color. Guess again.\n", guess)
	}
}

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é.

Comentarios de bloque

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.

// First line of a block comment
// Second line of a block comment

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.

/*
Everything here
will be considered
a block comment
*/

En este ejemplo, el comentario de bloque define lo que sucede en la función MustGet():

// MustGet will retrieve a url and return the body of the page.
// If Get encounters any errors, it will panic.
func MustGet(url string) string {
	resp, err := http.Get(url)
	if err != nil {
		panic(err)
	}

	// don't forget to close the body
	defer resp.Body.Close()
	var body []byte
	if body, err = ioutil.ReadAll(resp.Body); err != nil {
		panic(err)
	}
	return string(body)
}

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.

Comentarios incorporados

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:

[code]  // Inline comment about the code

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:

z := x % 2  // Get the modulus of x

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:

x := 8  // Initialize x with an arbitrary number

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.

Comentar código para pruebas

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.

// Function to add two numbers
func addTwoNumbers(x, y int) int {
	sum := x + y
	return sum
}

// Function to multiply two numbers
func multiplyTwoNumbers(x, y int) int {
	product := x * y
	return product
}

func main() {
	/*
		In this example, we're commenting out the addTwoNumbers
		function because it is failing, therefore preventing it from executing.
		Only the multiplyTwoNumbers function will run

		a := addTwoNumbers(3, 5)
		fmt.Println(a)

	*/

	m := multiplyTwoNumbers(5, 9)
	fmt.Println(m)
}

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.

Conclusión

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.