Documentação: no arquivo de implementação ou no arquivo de interface?

C++ é uma das linguagens com um modelo frágil na hora de importar declarações, pois a linguagem não define como importar declarações de nomes e a única técnica que nos resta é mágica de pré-processamento através de include e suas respectivas define guards, dentre algumas outras curiosidades. Mas o objetivo desse post não é discutir essa fragilidade. Além dessa fragilidade não-especificada, mas bem conhecida (pesquise por propostas para módulos em C++ se quiser mais informações), há o interessante padrão de separar abstrações em arquivos de implementação e arquivos de interface. Aliado a técnica de documentar as abstrações através de comentários (dessa vez sua pesquisa vai ser sobre Doxygen), no próprio código-fonte, surge a pergunta: A documentação deve ser feita no arquivo de implementação ou no arquivo de interface?

Eu sempre preferi colocar a documentação no arquivo de interface, pois tenho essa ideia estranha de que um dia haverão IDEs bem completas para C++ que serão capazes de mostrar a documentação para um nome baseado no conteúdo dos arquivos incluídos através da diretriz “#include” e isso (detecção automática da documentação) não funcionaria muito bem caso a documentação fosse feita nos arquivos de implementação, pois ela iria se perder. Claro que considero esse argumento um gosto pessoal, pois há preocupações do mundo real a considerar, como, por exemplo, o tamanho de um pacote de desenvolvimento de uma nova biblioteca. Mas recentemente eu estava brincando com a boost e lembrei que há muitas bibliotecas header-only, que não possuem arquivos de implementação e ao mesmo tempo lembrei da questão antiga abordada nesse post. Bom, esse seria um argumento definitivo para optar por incluir a documentação nos arquivos de interface, pois essa abordagem funciona sempre.

Tags:,

8 responses to “Documentação: no arquivo de implementação ou no arquivo de interface?”

  1. @_Kikuto says :

    Pois é. Isso é um bom questionamento… Eu gosto de fazer os comentários gerais na abstração e os específicos(Para no futuro eu me lembrar do passo a passo do que eu fiz) na implementação.

  2. Sales says :

    O eclipse (pelo menos a versão da BlackBerry, o momentics) mostra a documentação do cabeçalho quando você coloca o mouse em cima do nome da variável.

Comentários (with MarkDown support)

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair / Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair / Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair / Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair / Alterar )

Conectando a %s

%d blogueiros gostam disto: