Artigo

Código documentado

image

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.

  • Mauricio Junior

    Mauricio Junior