Comentários precisos e completos

Para deixar os comentários precisos e sem faltar conteúdo algumas dicas podem ser observadas:

• Evite palavras ambíguas

Cuidado com o pronome “ele” verifique se é claro o substantivo o qual se refere.

Exemplo:

// Insere o dado no cache, mas verifica se ele é grande demais.

Nesse exemplo não fica claro se será verificado o tamanho do cache ou do dado a ser inserido;

• Verifique se todo o comportamento da função está claro (não deixe funcionalidades ou detalhes ocultos). Se sua função prometer fazer uma coisa, mas no meio disso ela executar alguma outra tarefa, essa subtarefa deve ser descrita nos comentários de forma que quem for usar a função saiba de tudo que ela executa, para evitar surpresas desagradáveis no comportamento do sistema;

• Condense informações em palavras e expressões técnicas padrões. Aproveite que os futuros leitores serão técnicos e não leigos, e utilize expressões padrões para designar um comportamento conhecido.

Exemplo:

ao invés de

// Esta classe armazena a mesma informação que está na base de dados,

// mas é utilizada para desempenho. Quando esta classe for lida

// futuramente, irá checar primeiro se os campos existem e, se sim,

// retornará seus valores, se não, irá ler da base de dados e armazenar

// os valores nos campos da classe para a próxima vez.

pode simplesmente escrever

// Esta classe age como uma camada de cache para a base de dados