Quando ou não comentar em um código? Segundo o livro Código limpo: habilidades práticas do Agile software, comentar um código já é sim um fracasso!

Segue considerações do último encontro on-line de Leitura em Grupo que aconteceu no dia 17/04/2024:

• Comentários: Falamos sobre a importância dos comentários serem claros e necessários. Eles devem explicar o porquê de algo está sendo feito, não o que está sendo feito, pois o código deve ser auto explicativo.

• Comentários Ruins: Falamos sobre os tipos de comentários que devem ser evitados, como comentários óbvios, comentários redundantes, e comentários que contradizem o código.

• Comentários Bons: Falamos sobre os tipos de coisas que podem ser úteis, como comentários de esclarecimento, avisos sobre consequências não intuitivas e comentários que fornecem contexto histórico.

• Esclarecendo o Código: Falamos sobre a importância de escrever código claro e auto explicativo, eliminando a necessidade de comentários desnecessários.

• Comentários e Testes: Discutimos como os testes podem ser mais eficazes do que comentários para documentar o comportamento do código.

• Escrevendo Comentários Úteis: Vimos diretrizes para escrever comentários úteis, como ser claro e conciso, manter os comentários atualizados, e evitar comentários que enganam.

• Escolhendo Nomes Descritivos: Vimos novamente sobre a importância de escolher nomes descritivos para variáveis, métodos e classes, reduzindo a necessidade de comentários explicativos.

Se interessou? Comente esse post e envio o link do grupo que está discutindo quinzenalmente este livro! Seje bem-vinde!