Quando devo comentar meu código?

Comentários nem sempre são a melhor solução

Enquanto um comentário pode salvar muitas horas de trabalho, outros mil pode ocupar ainda mais tempo, antes de comentar um código veja as considerações abaixo:

Tenha em mente que, quem lê seu código é um desenvolvedor então evite barbaridades como:

Opte sempre pela refatoração ao invés de comentários:

Apesar do código acima, mesmo sem os comentários já seja auto-explicativo, seria mais viável refatora-lo, conforme exemplo abaixo:

Quanto mais antigos forem os comentários do seu código maiores são as chances dele não descrever exatamente o seu objetivo. Uma característica comum na maioria dos softwares são a capacidade de mudança, da mesmo forma que o software evoluí, o código fonte tem que acompanhar essas mudanças, nesse caso, os comentários nem sempre conseguem seguir o mesmo ritmo.

Segundo Robert C. Martin em seu livro Código limpo, Habilidades praticas do agile software.

Comentários imprecisos são muito piores do que nenhum. Eles enganam e iludem; deixam expectativas que jamais seriam cumpridas, citam regras antigas que jamais serão cumpridas, cita regras antigas que não precisam mais ou  não deveriam ser seguidas.

Outro ponto que deve levar em consideração é que; sempre que precisamos comentar o nosso código estamos tentando descrever algo que está incompreensível a qualquer ser humano :D. Então opte sempre pela refatoração como primeiro passo para descrever seu código e deixe os comentários para quando precisar notificar sobre algo que não seria possível expressar no seu código. Alguns exemplos são:

Péssimo

Abaixo segue uma implementação um pouco melhor já sem os comentários:

O exemplo acima ficou um pouco mais claro, porém ainda esta ambíguo  Data de entrada de que?, de quem? As perguntas anteriores podem martelar na sua cabeça, então devemos melhorar um puco mais a nomenclatura para que fique totalmente compreensível.

Vejo em muitos códigos fontes comentários para sinalizar o fechamento de chaves.

Irei apenas provocar a opinião de vocês sobre comentar ou não fechamento de instruções com três questões fundamentais:

  • Seu código possui indentação apropriada ?
  • Seu código possui mais de três níveis de instruções aninhadas ?
  • Possuí métodos ou funções com mais de 20 linhas?

Quando devo comentar?

Utilize os comentários quando necessita expressar algo que o seu próprio código não consiga fazer, ou seja, utilize os comentários para fazer notificações, relatar sobre bugs, dentre outros.