Documentação de código

Por Eduardo Miranda, Software Development Engineer da Microsoft

Outro dia na hora do almoço tivemos uma discussão animada sobre documentação de código. Que tipo de documentação é necessária para que um novo desenvolvedor tenha capacidade e segurança para fazer modificações em seu código-fonte?

Um dos meus colegas colocou a sua posição: Em uma situação ideal todo o código-fonte e design de um sistema deveriam ser tão claros e simples de entender que não existiria a necessidade de documentação nenhuma (Lembre-se que estamos falando somente de documentação de código-fonte e/ou design).

Lógico que houve reações contrárias. É muito difícil pegar um monte de código-fonte e sair “entendendo” ele. Alguma documentação facilita bastante este processo.

Pode ser, mas do ponto de vista de uma situação ideal, um código-fonte bem escrito, seguindo práticas básicas como separação de responsabilidade, alta coesão e ortogonalidade deveria ser bem fácil de entender. Posso parecer maluco, mas prefiro ler um trecho de código-fonte bem escrito do que ler a descrição em português do que aquele código faz (outros concordaram comigo no almoço, então não sou o único maluco :0).

Como não estamos ainda no mundo ideal, acho que o desenvolvedor deve se preocupar em manter o próximo coitado bem informado para um bom começo. Sempre utilizando as tags de documentação no próprio código-fonte. Segue a minha lista:

Classes

• Uma descrição breve da classe na tag summary é o suficiente.

• Os namespaces e padrões de nomenclatura devem estar bem definidos, isto ajuda bastante, por exemplo, se todas as entidades do sistema estiverem em MySystem.Entities, fica fácil de imaginar o que é a classe MySystem.Entities.Invoice

Métodos

• No mínimo, preencher as tags summary , param (para cada parâmetro) e returns (se o método tiver retorno) - Estas tags são importantes pois apareceção no intellisense quando você utilizar o método

• Se o método levanta erros preencher a tag exception.

• Se existirem testes unitários é desnecessário dar exemplos na tag example, pois testes unitários são os melhores exemplos de como utilizar uma classe e seus métodos.

• Se o código-fonte não estiver disponível para o usuário é interessante dar mais detalhes do método na tag remarks

• Ao longo do código só coloque comentários se o trecho for complicado

Para mim isto é mais do suficiente para documentar o código. O importante é fazer tudo isto no próprio código, utilizando as tags. Desta forma você só terá um artefato para atualizar e pode usar o moribundo NDoc ou o recém nascido SandCastle para gerar um help já formatado direto do código-fonte.

Decisões de design também podem ser documentadas em um documento simples de design, quais as decisões polêmicas que foram tomadas, design patterns utilizados. Tudo simples e rápido. Não deixe este documento ficar grande.

E você, tem alguma opinião a respeito? Deixe seu comentário.