Documentação do código: público versus não público?

Sou um desses desenvolvedores que tem a mentalidade de que o código escrito deve ser auto-explicativo e lido como um livro.

NO ENTANTO, ao desenvolver o código da biblioteca para outras pessoas, tento colocar o máximo de documentação possível nos arquivos de cabeçalho; o que levanta a questão: Os métodos de documentação que não são públicos valem o tempo? Eles não os usarão diretamente, de fato, não podem. Ao mesmo tempo, se eu distribuir o código bruto (embora com relutância), esses métodos não públicos estarão visíveis e talvez precisem ser explicados.

Basta procurar alguns padrões e práticas que todos vocês veem ou usam em suas viagens.

Eu nunca consideraria omitir documentação para internos apenas porque um "usuário final" não os utilizaria; a manutenção de código é motivo mais do que suficiente para incluir comentários na documentação de todos os componentes, de fato especialmente para internos que tendem a ser a parte mais complexa (e muitas vezes variável).

Dito isto, pode haver um argumento válido a ser mantido para mantê-los restritos ao código-fonte que não seja o cabeçalho (em vez de documentado publicamente), a fim de manter a abstração.

Tudo isso é subjetivo, lembre-se.

Aprovação, eu adiciono minha maneira de comentar / documentar demasiado à imagem para a variedade. A justificativa é que evito descrever funções ou funções-membro que são declaradas apenas no cabeçalho. Por um lado, receio adicionar muito ruído ao cabeçalho. Por outro lado, a documentação e a definição são mais fáceis de combinar pelo mantenedor. O Doxygen não se importa com os dois lados e pode filtrar as partes privadas se necessário.

No cabeçalho da classe:

• cabeçalhos incluídos (por que)
• definições de classe sempre (objetivo e responsabilidades)
• as funções virtuais puras sempre (contrato completo)
• as funções em linha, a menos que getters auto-explicativos
• outros tipos declarados, a menos que sejam auto-explicativos
• membros de dados estáticos (por que)
• outros membros dos dados, a menos que sejam auto-explicativos
• as macros, se houver (contrato e por que)

No código de implementação de classe:

• declarações locais da mesma maneira que no cabeçalho
• definições de função sempre (contrato completo)
• definições de função de membro sempre (contrato completo ou referência à raiz da substituição virtual)
• variáveis ​​estáticas definidas se houver (por que motivo)

No cabeçalho do modelo:

• o acima mesclado e
• tipos adequados / inadequados para argumentos de modelo e
• quão bem a adequação é detectada estaticamente

O private:início da seção privada é toda a documentação que os usuários precisam.

A documentação vale a pena em qualquer dia, pois ajuda a explicar casos de uso e histórias de uma maneira breve. Por mais que o código seja auto-explicativo, ele não pode explicar o negócio tão facilmente quanto poucas linhas de contar histórias. Definitivamente, o código exigiria que o usuário seguisse a lógica, além de entender o que está acontecendo. :-) Meus 2 centavos ...

Definitivamente!

Esse código deve ser auto-documentado é um slogan para se viver. No entanto, eu chegaria ao ponto de dizer que o código privado precisa de tanta documentação, se não mais, do que o código público, porque geralmente é aqui que a maioria das suposições geralmente ocorre, apenas porque o codificador assume que permanecerá no escuro . Assim, alguns meses depois, quando um bug aparecer, você passará um tempo tentando lembrar qual foi a idéia por trás do código (talvez você mesmo) escreveu.

A documentação não deve ser um presente agradável para os outros. A documentação, em todas as suas faces (nomes de variáveis ​​bem escolhidos, nomes de classe com documentação automática, código bem organizado, métodos adequadamente segmentados etc.) é um presente para todos que possam entrar em contato com seu código, inclusive você.