É melhor documentar funções no arquivo de cabeçalho ou no arquivo de origem?

Nas linguagens que distinguem entre um arquivo "fonte" e "cabeçalho" (principalmente C e C ++), é melhor documentar funções no arquivo de cabeçalho:

(roubado do CCAN )

/**
 * time_now - return the current time
 *
 * Example:
 *  printf("Now is %lu seconds since epoch\n", (long)time_now().tv_sec);
 */
struct timeval time_now(void);

ou no arquivo de origem?

(roubado do PostgreSQL)

/*
 * Convert a UTF-8 character to a Unicode code point.
 * This is a one-character version of pg_utf2wchar_with_len.
 *
 * No error checks here, c must point to a long-enough string.
 */
pg_wchar
utf8_to_unicode(const unsigned char *c)
{
...

Observe que algumas coisas são definidas apenas no cabeçalho, como estruturas, macros e static inlinefunções. Estou falando apenas de coisas que são declaradas em um arquivo de cabeçalho e definidas em um arquivo de origem.

Aqui estão alguns argumentos em que consigo pensar. Estou inclinado a documentar no arquivo de origem, então meus argumentos "Pro-header" podem ser um pouco fracos.

Cabeçalho profissional:

• O usuário não precisa do código fonte para ver a documentação.
  • A fonte pode ser inconveniente ou até impossível de adquirir.
  • Isso mantém a interface e a implementação ainda mais separadas.

Pro-fonte:

• Isso torna o cabeçalho muito mais curto, oferecendo ao leitor uma visão panorâmica do módulo como um todo.
• Ele associa a documentação de uma função à sua implementação, facilitando ver que uma função faz o que diz que faz.

Ao responder, tenha cuidado com argumentos baseados no que as ferramentas e os "IDEs modernos" podem fazer. Exemplos:

• Cabeçalho profissional: a dobragem de código pode ajudar a tornar os cabeçalhos comentados mais navegáveis ​​ocultando os comentários.
• Pro-source: o recurso do cscopeFind this global definition leva você ao arquivo de origem (onde está a definição ) e não ao arquivo de cabeçalho (onde está a declaração ).

Não estou dizendo que não faça tais argumentos, mas lembre-se de que nem todo mundo se sente à vontade com as ferramentas que você usa.

Minha visão...

• Documente como usar a função no arquivo de cabeçalho ou mais perto da declaração.

• Documente como a função funciona (se não for óbvia no código) no arquivo de origem ou, mais precisamente, próximo à definição.

Para a coisa de passarinho no cabeçalho, você não precisa necessariamente da documentação que fecha - você pode documentar grupos de declarações de uma só vez.

De um modo geral, o chamador deve estar interessado em erros e exceções (apenas para que possam ser traduzidos à medida que se propagam pelas camadas de abstração); portanto, esses documentos devem ser documentados próximo às declarações relevantes.

Se você usar uma ferramenta como o Doxygen (observe no primeiro exemplo, que realmente se parece com um comentário do Doxygen porque começa com /**), isso realmente não importa - o Doxygen examinará seus arquivos de cabeçalho e de origem e encontrará todos os comentários para gerar a documentação.

No entanto, eu estaria mais inclinado a colocar os comentários da documentação nos cabeçalhos, onde estão as declarações. Seus clientes vão lidar com os cabeçalhos para interagir com seu software, os cabeçalhos são o que incluirão em seus próprios arquivos de origem e é aí que eles procurarão primeiro ver a aparência da sua API.

Se você observar a maioria das bibliotecas Linux, por exemplo, seu sistema de gerenciamento de pacotes Linux geralmente possui um pacote que contém apenas os binários da biblioteca (para usuários "normais" que possuem programas que precisam da biblioteca) e você tem um pacote "dev" que contém os cabeçalhos da biblioteca. O código fonte normalmente não é fornecido diretamente em um pacote. Seria realmente complicado se você tivesse que obter o código fonte de uma biblioteca em algum lugar para obter a documentação da API.

Resolvemos esse problema (há cerca de 25 anos) criando um monte de #defines (por exemplo, público, privado, etc., resolvidos para <nenhum>) que poderiam ser usados ​​no arquivo de origem e verificados por um script awk (horrores !) para gerar automaticamente os arquivos .h. Isso significa que todos os comentários residiram na fonte e foram copiados (quando apropriado) no arquivo .h gerado. Eu sei que é uma velha escola, mas simplificou bastante esse tipo de documentação embutida.

Supondo que este seja um código dentro de um projeto maior (onde os desenvolvedores costumam se mover entre a fonte e os cabeçalhos) , e fornecendo que isso não seja uma biblioteca / middleware, onde outras pessoas podem não ter acesso à fonte, descobri que isso funciona melhor...

• Cabeçalhos:
  comentários concisos de 1 a 2 linhas, apenas se forem necessários.
  Às vezes, comentários acima de um grupo de funções relacionadas também são úteis.
• Fonte:
  documentação na API diretamente acima da função (texto simples ou doxygen, se você preferir) .
• Mantenha os detalhes da implementação, relevantes apenas para um desenvolvedor que modifique o código no corpo da função.

A principal razão para isso é manter os comentários próximos ao código, notei que os documentos nos cabeçalhos tendem a ficar fora de sincronia com as alterações no código com mais frequência (é claro que não deveriam, mas fizeram no nosso projeto em menos) . Os desenvolvedores também podem adicionar documentação na parte superior das funções quando fazem alguma alteração, mesmo se houver documentos de cabeçalho ... em outro lugar. Causando duplicatas ou informações úteis apenas em uma das strings de documentos.

Claro que você pode escolher uma convenção e garantir que todos os desenvolvedores sigam. Acabei de encontrar a convenção acima da forma mais natural e com menos problemas de manutenção.

Por fim, para projetos grandes - há uma tendência a não fazer pequenas correções em um cabeçalho quando você sabe que isso fará com que centenas ou milhares de arquivos sejam recompilados quando outros atualizam o controle de versão - diminuindo também os erros de divisão.

Na minha opinião (bastante limitada e tendenciosa), sou uma maneira de pensar em código pró-fonte. Quando eu faço bits e partes em C ++, geralmente edito o arquivo de cabeçalho uma vez e nunca mais volto a examiná-lo.

Quando coloco a documentação no arquivo de origem, sempre a vejo quando estou editando ou lendo códigos. Eu acho que é uma coisa de hábito.

Mas isso sou só eu ...

Comentários não são documentação. A documentação para uma função geralmente pode ter 2K de texto, possivelmente com diagramas - consulte, por exemplo, a documentação para funções no SDK do Windows. Mesmo se o seu comentário ao documento permitir isso, você estará tornando o código que contém o comentário ilegível. Se você deseja produzir documentação, use um processador de texto.

Se os participantes do seu código-fonte (digamos, uma pequena biblioteca) consistirem em "usuários" (colegas desenvolvedores que usarão a funcionalidade da sua biblioteca sem se envolver na implementação) e "desenvolvedores" (você e outros desenvolvedores que implementarão a biblioteca) , coloque as "informações dos usuários" no cabeçalho e a "nota de implementação" na fonte.

Com relação ao desejo de não alterar os arquivos de cabeçalho mais do que o absolutamente necessário - suponho que se sua biblioteca não estiver "em um fluxo louco de mudanças", que a "interface" e a "funcionalidade" não mudem muito, e nem os comentários do cabeçalho devem mudar com muita frequência. Por outro lado, os comentários do código-fonte deverão ser mantidos sincronizados ("atualizados") com o código-fonte.

O objetivo principal do uso do doxygen é que você gera documentação e a torna acessível em outro lugar. Agora toda essa documentação nos cabeçalhos é apenas lixo, o que torna mais difícil detectar rapidamente a declaração de função necessária e talvez suas sobrecargas. O comentário de um forro é o máximo que deve ir para lá, mas mesmo isso é uma má prática. Porque, se você alterar a documentação na fonte, recompila essa fonte e vincula novamente. Mas se você colocar documentos no cabeçalho, realmente não deseja alterar nada, porque isso acionará parte significativa da reconstrução do projeto.