Guia de estilo para pacotes Go - Avelino
Apr 2, 2018 | 8 minutes read
O objetivo deste blogpost é ajudá-lo(a) com boas práticas comuns para não definir regras ruins. Você deve sempre usar o seu julgamento para escolher a solução mais elegante para sua implementação.
A linguagem Go não restrige onde você deve definir os tipos, uma boa prática é manter os tipos na parte superior do arquivo, dentro do pacote que ele faz parte.
Não é muito facil pensar (usar) Godoc na fase inicial do desenvolvimento da API do seu pacote para ver como seus conceitos serão renderizados no doc. Muitas vezes, essa visualização tem um impacto sobre o projeto (em geral para melhor). Godoc é a forma como os usuários vão consumir um pacote, por isso é extremamente importante ajustar as coisas para torná-las mais acessíveis, tenha certeza que isso melhora a API dos seus pacotes.
Em alguns casos, talvez não seja possível fornecer todos os tipos relacionados de um único pacote. Pode ser confuso fazer isso (em uma fase inicial), você pode querer publicar implementações concretas de uma interface comum de pacote separado ou esses tipos podem ser propriedade de um pacote de terceiros. Dê exemplos para ajudar o usuário a descobrir e entender como eles são usados juntos.
NewClient trabalha com option.ClientOptions mas não é nem o pacote de armazenamento de informações nem o pacote de opção que exporta todos os tipos de opção.
Exemplos é uma ótima maneira de aumentar a visibilidade de um pacote menos descoberto. Por exemplo, para datastore.NewClient pode referenciar o pacote de opção extra.
Exceções a esta regra podem ser os principais pacotes incorporados um .so, .a ou Go plugin. Em tais casos, código Go pode ser usado a partir de outras linguagens através da funcionalidade exportar CGO e identificadores de exportação são necessários.
Evite nomes de pacotes demasiado amplos como "common" e "util".
Evite nomes duplicados em casos que o usuário precise importar o mesmo pacote.
Se você não pode evitar um nome ruim, é muito provável que haja um problema com sua estrutura geral e organização de código, esse é um grande alerta para repensar do design da sua API.
Se você estiver importando mais de um pacote com o mesmo nome, poderá renomear localmente os nomes dos pacotes. Os renomes devem seguir as mesmas regras mencionadas neste blogpost. Não há nenhuma regra sobre que pacote que você deve renomear. Se você está renomeando a biblioteca de pacotes padrão, é bom adicionar um prefixo Go para fazer o nome de auto documento que é "Go biblioteca padrão" pacote, por exemplo, gourl, goioutil.
URLs personalizada (vaidade)
go get suporta a obtenção de pacotes por uma URL que seja diferente da URL do repositório do pacote. Estas URLs são chamadas de URLs personalizadas e exigem que você sirva uma página com meta tags específicas que as ferramentas Go reconhecem. Você pode servir um pacote com um domínio personalizado e um caminho usando URLs personalizadas.
Dado code.googlesource.com/gocloud já está servindo este pacote, seria possível ir buscar o pacote a partir desse URL? A resposta é não, se você impor a URL personalizada.
Às vezes, os docs do pacote podem ser longos, especialmente quando fornecem detalhes do uso e das diretrizes. Quando isso acontecer mova o pacote godoc para um arquivo doc.go. (consulte um exemplo de um doc.go.)