Primeiro tivemos o post sobre código sem comentários, depois o post abordando comentários em excesso, agora, finalmente, veremos algo que devemos usar: código autodocumentado.

Do que se trata?

Um código é autodocumentado quando você pode compreendê-lo facilmente apenas lendo o seu arquivo fonte. Para atingir tal nível de fluência, além de um programador que conheça a linguagem utilizada, precisamos que a maior parte do código fonte seja perfeitamente claro, além disso, devemos também comentar os trechos de código complexos que eventualmente existirem.

Escrevendo código claro

Talvez a tarefa mais difícil na busca por um código autodocumentado seja programar de forma extremamente clara, não só para si, como também para todos os outros programadores. Para conseguir isto você precisará de prática, dedicação e até mesmo uma certa dose de talento. Ou seja, não é nada fácil, e é justamente por isso que eu disponibilizo abaixo algumas dicas para facilitar esta atividade.

1. Siga as convenções da linguagem de programação que você utiliza, mesmo que você não goste delas. Fazendo isso, você irá reduzir a surpresa dos outros programadores e adestrar o pensamento de forma a reconhecer automaticamente certas construções.
2. Dê nomes intuitivos a todas as estruturas do seu programa. Isto inclui, por exemplo, classes, variáveis, métodos, arquivos, entre outros. Fazendo isto, ninguém irá parar pra pensar no propósito dos elementos que compõem seu software, possibilitando assim uma leitura mais fluente.
3. Escreva código que cumpra o objetivo, e só. Não escreva nada desnecessário, lembre-se que quanto menos linhas melhor.
4. Não escreva métodos longos. Se um método acaba se prolongando, é provável que ele faça coisas demais, devendo assim ser refatorado em dois ou mais métodos.
5. Evite escrever instruções excessivamente longas ou complexas. Em geral, essas instruções podem ser decompostas, e, ainda que isto signifique mais linhas de código, é melhor do que criar um ponto potencialmente complexo.

Escrevendo comentários

Clareza no código é apenas metade do necessário para termos código autodocumentado, sendo o uso de comentários a outra metade. Esta necessidade se dá devido a natureza complexa do software, pois mesmo quando escrevemos código de forma clara, poderão existir trechos do código onde a compreensão seja naturalmente mais difícil, sendo preciso usar comentários para resolver o problema.

Contudo, é importante ressaltar que apenas comentar não adianta nada. Temos que fazer o comentário valer a pena, afinal, mesmo ele sendo necessário neste caso, ainda implicará em mais tempo para escrever, ler e manter o programa.

Tendo isto em vista, separei abaixo algumas poucas dicas que talvez possa ajudá-lo a escrever bons comentários:

1. A menos que esteja trabalhando com uma equipe muito grande, não é necessário escrever comentários referentes a autoria dos códigos. Em geral, uma divisão de tarefas adequada já se encarrega de definir claramente quem faz o quê.
2. Escreva comentários somente para trechos de código complexos. Um comentário para descrever o objetivo de um elemento do programa é desnecessário, uma vez que um bom nome já é o suficiente. Por exemplo, não é preciso comentar o objetivo de uma classe chamada LoginController, uma vez que o nome não deixa dúvidas sobre o seu propósito.
3. Quando for escrever um comentário, não fale sobre a sintaxe do código, e sim da sua semântica no domínio da aplicação. Lembre-se que você está comentando um programa, e não a linguagem utilizada.
4. O comentário deve ser absolutamente claro sobre o trecho de código que ele está explicando, de forma a não restar dúvida alguma sobre o seu funcionamento.
5. Os comentários são apenas pequenos textos explicativos, e não artigos, portanto, seja sucinto e evite comentários com muitas linhas. Se puder utilizar apenas uma linha, melhor.

Use apenas o que gostar

As dicas acima não são dogmas, assim como tudo mais que eu disse nessa série de posts. Trata-se apenas da minha opinião sobre esta questão, logo, sinta-se a vontade para ignorar parte das dicas, parte do que eu disse, ou até mesmo tudo que leu nestes posts. Cada um tem sua maneira de desenvolver software, e eu estou longe de ter autoridade suficiente pra dizer que alguém está errado simplesmente porque discorda do que eu acredito ser o ideal.