Como escrever comentários em Go

Introdução

Comentários são linhas que existem em programas de computador que os programas de compilação e interpretação ignoram. A inclusão de comentários nos programas torna o código mais legível para humanos, uma vez que fornece informações ou explicações sobre o que cada parte de um programa está fazendo.

Dependendo do objetivo do seu programa, os comentários podem servir como notas para si mesmo ou lembretes, ou podem ser escritos com a intenção de fazer com que outros programadores entendam o que o seu código está fazendo.

De um modo geral, é uma boa ideia escrever comentários enquanto está escrevendo ou atualizando um programa, uma vez que é fácil esquecer seu processo de pensamento mais tarde. Além disso, os comentários escritos posteriormente podem ser menos úteis no longo prazo.

Sintaxe do comentário

Os comentários em Go começam com um conjunto de barras (//) e continuam até o final da linha. Ter um espaço em branco após o conjunto de barras refere-se a uma regra idiomática apenas.

Geralmente, os comentários terão uma aparência como a deste:

// This is a comment

Os comentários não são executáveis. Assim, não haverá indicação de um comentário ao se executar um programa. Os comentários existem no código fonte para que os humanos os leiam e não para que os computadores os executem.

Em um programa “Hello, World”! , um comentário pode se parecer com este:

package main

import (
	"fmt"
)

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

Num loop for que itera em uma fatia, os comentários podem se parecer com este:

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)
	}
}

Os comentários devem ser feitos no mesmo recuo do código sobre qual estiver falando. Ou seja, uma definição de função sem recuo teria um comentário sem recuo e cada nível de recuo seguinte teria comentários alinhados ao código que estivesse sendo comentando.

Por exemplo, aqui está como a função main foi comentada. Os comentários seguem cada nível de recuo do 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)
	}
}

Os comentários são feitos para ajudar os programadores, seja o programador original ou outra pessoa usando ou colaborando no projeto. Se os comentários não puderem ser mantidos e atualizados corretamente com a base de código, é melhor que não se incluam comentários, em vez de escrever um comentário que contradiga ou vá contradizer o código.

Ao comentar o código, você deve procurar responder à pergunta por que por trás do código ao invés de o que ou como. A menos que o código seja particularmente complicado, de maneira geral, examinar o código basta para responder o o que ou como, motivo pelo pelo qual os comentários normalmente se concentram no por que.

Comentários em bloco

Os comentários em bloco podem ser usados para explicar códigos complicados ou códigos com os quais você não espera que o leitor esteja familiarizado.

Você pode criar comentários em bloco de duas maneiras em Go. A primeira é usar um conjunto de barras duplas e repeti-las a cada linha.

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

A segunda é usar identificadores de abertura (/*) e identificadores de encerramento (*/). Para documentar o código, usar sempre a sintaxe de // é considerada como uma decisão idiomática. Você somente usará a sintaxe /* ... */ na depuração, sobre a qual valor falar mair adiante neste artigo.

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

Neste exemplo, o comentário em bloco define o que está acontecendo na função 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)
}

É comum ver comentários em bloco no início das funções exportadas em Go; esses comentários também são o que gera a documentação do seu código. Os comentários em bloco também são usados quando as operações são menos objetivas e, portanto, exigem uma explicação mais detalhada. Com exceção da documentação sobre as funções, evite o excesso de comentários sobre o código e confie em que os demais programadores entenderão a linguagem Go, a menos que você esteja escrevendo para um público em particular.

Comentários feitos na linha

Os comentários são feitos na mesma linha de uma instrução, após o código, propriamente dito. Assim como outros comentários, eles começam com um conjunto de barras. Novamente, não é necessário ter um espaço em branco após as barras, mas é considerada uma regra idiomática usá-las.

Geralmente, os comentários feitos na linha se parecem com este:

[code]  // Inline comment about the code

Os comentários na linha devem ser usados com moderação, mas podem ser eficazes para explicar partes do código complicadas ou não óbvias. Eles também podem ser úteis se você achar que, no futuro, poderá não se lembrar de uma linha do código que está escrevendo, ou se estiver colaborando com alguém que você sabe que talvez não esteja familiarizado com todos os aspectos do código.

Por exemplo, caso não use muita matemática nos seus programas em Go, você ou seus colaboradores podem não saber que o seguinte cria um número complexo, então você pode querer incluir um comentário na linha sobre isso:

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

Também é possível usar comentários na linha para explicar a razão para estar fazendo algo, ou fornecer algumas informações extras, como em:

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

Você somente deve usar os comentários na linha quando necessário e quando eles puderem proporcionar orientações úteis para a pessoa que lê o programa.

Comentando o código para fins de teste

Além de usar comentários como uma maneira de documentar o código, também é possível usar sinalizadores de abertura (/*) e sinalizadores de encerramento (*/) para criar um comentário em bloco. Isso permite que você faça um comentário sobre o código, dizendo que não deseja executar enquanto estiver testando ou depurando um programa que estiver criando no momento. Ou seja, quando aparecerem erros após implementar novas linhas do código, você pode querer fazer comentários em algumas delas para ver se pode resolver esse problema específico.

Usar os sinalizadores /* e */ também pode permitir que você tente alternativas enquanto estiver determinando como configurar o seu código. Também é possível usar blocos de comentários para fazer comentários sobre um código que estiver apresentando falhas, enquanto você continua a trabalhar em outras partes do seu 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)
}

Fazer comentários no código usando os sinalizadores /* e */ pode permitir que você experimente outros métodos de programação, bem como pode ser útil para que você encontre a fonte de um erro através de comentários feitos sistematicamente e da execução de partes de um programa.

Conclusão

Usar comentários dentro dos seus programas em Go ajuda a tornar seus programas mais legíveis para os humanos, inclusive para você mesmo, no futuro. Adicionar comentários apropriados - que sejam relevantes e úteis - pode facilitar que outras pessoas colaborem com você em projetos de programação e pode tornar o valor do seu código mais óbvio.

Comentar seu código corretamente em Go também permitirá que você use a ferramenta Godoc. Godoc é uma ferramenta que extrairá os comentários do seu código e gerará uma documentação para o seu programa em Go.