Quando você pensa em programação, é natural focar em tópicos como linguagens, algoritmos e depuração. Mas a documentação técnica pode ser tão importante para acertar.

Sem uma boa documentação, a reutilização do código pode ser prejudicada. Os usuários novos em uma base de código podem facilmente se perder ou ficar frustrados se a documentação não estiver atualizada. Não é importante apenas entender o que um programa faz, mas como — ou mesmo por que — ele o faz.

Pacotes como Pydoc para Python e Javadoc para Java ajudam automatizando parte do processo. A ferramenta Godoc faz exatamente o mesmo para Go.

O que é Godoc?

Godoc é um pacote Go que permite criar, gerenciar e usar a documentação Go no “jeito Go”. O caminho Go é um conjunto de princípios que, como programador Go, você deve seguir para melhorar a qualidade do código.

Usando Godoc, você pode ler facilmente a documentação e o código de outros desenvolvedores. Você também pode automatizar a criação de sua própria documentação e publicá-la usando Godoc.

Godoc é semelhante a Javadoc, o documentador de código para Java. Ambos usam comentários e código em módulos para gerar documentação. E ambas as ferramentas estruturam essa documentação em HTML para que você possa visualizá-la em um navegador.

Introdução ao Godoc

Usar Godoc é fácil. Para começar, instale o pacote Godoc do site golang usando este comando:

vai obtenha golang.org/x/tools/cmd/godoc

A execução deste comando instalará o Godoc em seu espaço de trabalho especificado. Depois de concluído, você deve ser capaz de executar o godoc comando em um terminal. Se houver algum erro com sua instalação, tente atualizar o Go para uma versão recente.

Godoc procura comentários de linha única e múltipla para incluir na documentação que gera.

Certifique-se de formatar o código da maneira Go, conforme explicado em a publicação Effective Go pela equipe Go para obter os melhores resultados.

Aqui está um exemplo usando comentários de linha única no estilo C++:

// User é um modelo struct contendo
modelo Do utilizador estrutura {
}

Você também pode usar comentários de bloco no estilo C:

/* 
O usuário é uma estrutura de dados personalizada
Você pode incluir qualquer texto aqui e o servidor Godoc irá formatá-lo quando você executá-lo.
*/
modelo Do utilizador estrutura {
}

Nos comentários acima, “User” inicia as frases porque o comentário descreve o que a estrutura User faz. Este é um dos muitos tópicos que o caminho Go discute. Iniciar frases de documentação com um nome útil é crucial, pois a primeira frase aparece na lista de pacotes.

Executando um servidor Godoc

Depois de comentar seu código, você pode executar o godoc comando em seu terminal, do diretório de código do seu projeto.

Convencionalmente, os desenvolvedores Go usam 6060 para hospedar a documentação. Este é o comando para executar um servidor Godoc nessa porta:

godoc -http=:6060

O comando acima hospeda sua documentação de código em localhost ou 127.0.0.1. A porta não precisa ser 6060; godoc será executado em qualquer porta desocupada. No entanto, é sempre melhor seguir as convenções de documentação do Go.

Depois de executar o comando, você pode visualizar sua documentação em um navegador visitando localhost: 6060. O tempo que o Godoc leva para gerar sua documentação dependerá de seu tamanho e complexidade.

O código abaixo segue o caminho Go, neste caso usando comentários de linha única.

// nome do pacote
pacote do utilizador
// fmt é responsável pela formatação
importar (
 "fm"
)


// O usuário é uma estrutura de dados humanos
modelo Do utilizador estrutura {
 Era int
 Nome corda
}


funçãoa Principal() {
// humano é uma inicialização da estrutura User
 humano := usuário {
 Era: 0,
 Nome: "pessoa",
 }


fmt. Println (humano. Conversa())
}
// Talk é um método da estrutura User
função(usuário receptor)Conversa()corda {
Retorna "Todo usuário pode dizer alguma coisa!"
}

Se você executar Godoc no módulo de código acima, deverá ver a saída parecida com esta:

Observe que está em um formato familiar, semelhante ao que você encontrará no site de documentação oficial do Go.

Godoc usa o comentário que precede a declaração do pacote como o Visão geral. Certifique-se de que este comentário descreva o que seu programa faz.

o Índice contém links para as declarações de tipo e métodos para que você possa navegar até eles rapidamente.

Godoc também oferece funcionalidade para visualização do código fonte que compõe o pacote no Arquivos de pacote seção.

Melhorando sua documentação usando Godoc

Você pode incluir mais do que apenas texto simples em sua documentação Godoc. Você pode adicionar URLs para os quais Godoc irá gerar links e estruturar seus comentários em parágrafos.

Se você deseja vincular a um recurso, escreva o URL em seu comentário e Godoc o reconhecerá e adicionará um link. Para parágrafos, deixe uma linha de comentário vazia.

// Pacote principal
pacote a Principal
// Documento representa um documento normal.
//
// Link para https://google.com
modelo Documento estrutura {
 Páginas int
 referências corda
 assinado bool
}


// Write grava um novo Documento no armazenamento
//
// Você pode aprender a escrever na Wikipedia.com
funçãoEscreva() {
}

Observe que Godoc exige que você escreva URLs na íntegra para vinculá-los. Neste exemplo, o URL do Google inclui o https:// prefixo, então Godoc adiciona um link para ele. Como o domínio da Wikipedia não é um URL completo por si só, Godoc o deixará em paz.

Aqui estão alguns dos melhores princípios a serem aplicados ao documentar seu código Go:

  • Mantenha sua documentação simples e concisa.
  • Inicie a sentença de funções, tipos e declarações de variáveis ​​por seus nomes.
  • Inicie uma linha com um recuo para pré-formatá-la como código.
  • Comentários que começam com "BUG(name)" como "BUG(joe): Isso não funciona" são especiais. Godoc irá reconhecê-los como bugs e reportá-los em sua própria seção da documentação.

Godoc pode aliviar seus problemas de documentação

Usando Godoc, você pode ser mais produtivo e se preocupar menos com o esforço de documentar seus programas manualmente.

Você deve manter sua documentação precisa, detalhada e direta para facilitar a leitura e a compreensão do seu público-alvo. Também é vital que você mantenha os comentários de código atualizados enquanto modifica seu programa.

Confira a documentação do pacote Godoc para saber mais sobre como usar Godoc.