Código documentado

Olá pessoal meu nome é Mauricio Junior e hoje eu vou falar um pouco sobre código documentado. Vou tentar explicar da maneira o que eu penso sobre documentação de código.

Mas antes eu vou tentar colocar aqui algumas perguntas que recebo diariamente:

1. É necessário documentar todo o sistema?
2. Você acha que não precisa documentar ?
3. Que parte do sistema você acha que é importante ter algum tipo de documento?
4. Como você usa as facilidades de documentação?
5. Os frameworks e interfaces que você usa possuem documentação para facilitar o uso?
6. O método que você chama dentro de um framework possui comentários na assinatura do método?

Antes de começar a falar sobre esses questionamentos eu gostaria de dizer que, o que for falado aqui é o que eu uso para mim e é uma opinião pessoal baseado na experiência que tenho durante todos esses anos trabalhando como desenvolvedor de software no Brasil, Europa e agora nos Estados Unidos.

Vamos para as perguntas.

1. É necessário documentar todo o sistema?

A minha resposta é não, até porque se você usa o conceito de SOLID todos os seus métodos serão pequenos, os nomes das variáveis serão auto-explicativas e quando olhar o código dentro de qualquer classe você e qualquer outro desenvolvedor vai entender.

Mas se você não usa SOLID, então é necessário fazer alguns comentários e documentos explicando o que está fazendo. Acredito que pelo menos algum mindmap sobre o fluxo ou regra do sistema é necessário.

Se você ainda não viu sobre mindmap, pesquise na Internet o esse assunto e depois tente vincular na área da programação. É assim que eu uso.

2. Você acha que não precisa documentar ?

Eu sinceramente acho que precisa ter algum tipo de documento explicando algumas coisas básicas sobre o sistema, site, web app, framework, package, serviço ou qualquer outro sistema desktop.

Hoje existem várias maneiras de documentar de forma divertida, como usar o mindmap. Existe o comentário dentro do código que ajuda em alguns momentos confusos, existem também as três barras /// na assinatura do método essenciais para frameworks e pacotes; e para finalizar existem os arquivos .MD (markdown) utilizado muito pelo GIT e TFS para gerar um documento de entrada falando um pouco sobre o sistema em geral que está fazendo. Tudo isso ajuda a documentar pelo menos o mínimo sobre o que está fazendo.

3. Que parte você acha que é importante ter algum tipo de documento?

Eu acredito que não existe o que é mais ou menos importante. Pra mim, o que deve ser essencial é algo falando como o sistema funciona, um fluxo mostrando os passos ou até mesmo como executar, pacotes vinculados e tudo mais.

Em alguns momentos eu tive que comentar o código apenas para ficar melhor explicado, em outros momentos eu tive que fazer um fluxograma sobre o sistema e em outros não precisei fazer nada, apenas uma frase no arquivo .MD porque era muito simples.

4. Como você usa as facilidades de documentação?

No JavaScript existe o asterisco e barra, no HTML posso usar as tags <!-- --!> no C# existe as três barras /// que já monta o cabeçalho do método e com os campos necessários baseados na interface, método ou função.

Outra facilidade que utilizo é o mindmap tornando simples de explicar para o gerente, explicar para o usuário ou até mesmo para eu lembrar de como funciona alguma coisa.

São essas facilidades que uso no dia a dia.

5. Os frameworks e interfaces que você usa possuem documentação para facilitar o uso?

Quando eu faço um framework, a primeira ideia é ajudar alguém ou prover alguma solução para a empresa ou desenvolvedor que vai utilizar. Pra isso, é necessário documentar algumas partes expostas ao usuário utilizador, na minha opinião.

Os frameworks que utilizo precisam pra mim ter alguma documentação direta ou simples. Sem nenhum tipo de explicação eu não dou muita credibilidade.

O usuário precisa saber sobre o que exatamente o funcionamento do método ou então pelo menos identificar o básico para utilizar. É bom até colocar um exemplo de código no comentário. Assim o usuário vê o que precisa fazer, como nos frameworks da Microsoft.

6. O método que você chama dentro de um framework possui comentários na assinatura do método?

Sim, eu gosto de ler e analisa o que precisa passar como parâmetro. A ajuda te da um rumo em muitos aspectos na programação de software. Eu recomendo e faço isso sempre, quero dizer, coloco os comentários necessários para quem vai chamar e usar a interface. Para API, normalmente eu utilizo o Swagger que ajuda muito também.

Essas perguntas que respondi são apenas para que você pense a respeito de comentário em código. Pense na facilidade de entendimento e manutenção, pense que outra pessoa vai atualizar ou manter o código que você fez.

Eu fico por aqui e qualquer dúvida você pode me encontrar no instagram @mauriciojunior_net ou no meu site pessoal www.mauriciojunior.net.