Documentar é importante?

Existem várias formas de documentação, mas irei falar especificamente de documentação de código fonte.

Existe coisa pior do que precisar entender um código e não ter nenhum tipo de documentação ou simplesmente documentações desatualizadas? Se isso já aconteceu, e tenho certeza que sim, você deve saber o tempo que é gasto para tentar entender um bloco de código, que poderia ser reduzido consideravelmente se corretamente documentado.

Mas por que documentar ou melhor por que os desenvolvedores simplesmente não documentam? Talvez por preguiça ou talvez aparece outra atividade pra fazer e deixar pra documentar depois.

Já ouvi coisas do tipo: “Não temos tempo para isso” ou “Deixei para documentar o código quando terminasse tudo”, isso é o que já ouvi comentarem. OPA! Documentar ou comentar? Existe diferença? Sim e ainda comentar pode ajudar tanto quanto documentar.

Então comentário é uma parte próxima do código que você quer explicar, geralmente para explicar uma ou duas linhas de código. Por exemplo:

// The size of the ArrayList (the number of elements it contains).
private int size;

Documentação já é uma visão mais ampla de um comentário. Um comentário pode ser uma documentação, mas não o contrário, justamente por comentários serem aplicados a uma ou duas linhas de código e documentação compõem um método inteiro, uma lista de funções ou uma classe inteira. Por exemplo:

/**
* Removes all of the elements from this list. The list will
* be empty after this call returns.
*/
public void clear() { }

Mas por que documentar afinal? Além de facilidade para entender o código, manutenção de código, redução considerável de tempo para entender trechos de código, organização e etc. Escrever documentação sempre pensando que alguém irá olhar aquele código futuramente e que irá dar continuidade ao seu trabalho.

Vejam o comentário de um Analista desenvolvedor Notes:

/**
* @Author Rodrigo Freitas – Analista Desenvolvedor Notes
* A documentação de código é importantíssima para o bom entendimento e manutenções futuras de
* qualquer sistema, visto que uma falta de documentação pode gerar mal entendimento de outro ou até
* mesmo do próprio desenvolvedor, além disso podemos citar também o ganho de tempo quando
* eliminamos a necessidade de entender tudo o que já está feito antes de darmos manutenção.
*/

Escrevi esse post para incentivar dos desenvolvedores para comentarem e documentarem seus códigos, para que outros desenvolvedores, quem sabe até eu, possam olhar aquele código um dia e ser elogiado pela ótima documentação.

Deveriam fazer com que blocos de códigos não pudessem ser comitados sem antes ser documentados corretamente, assim como em testes, pelo menos dessa forma que deveria ser. Ai entra a participação de uma pessoa mais experiente para analisar e a ajuda de um code view, mas isso é assunto para outro post ;)