Código comentando o que fazer e o que não fazer

O ato de desenvolvimento de software é desafiador em todas as frentes. A tarefa de programar não é apenas muitas vezes repleta de obstáculos, quando alguém é confrontado com o trabalho no código de outra pessoa que não faz uso de comentários, mas esse trabalho também se torna exponencialmente mais difícil.

Pense desta forma: imagine receber todos os ingredientes para fazer pão, mas nenhuma receita. Você sabe que os ingredientes secos combinam, mas talvez não saiba as quantidades de cada um. O mesmo se aplica aos comentários de código que podem ajudar a servir como uma espécie de resumo sobre como um programador usou uma função ou como algo foi alterado para enfrentar um determinado desafio.

Os comentários do código são essenciais para uma programação eficiente e eficaz. Joel Spolsky (co-criador do StackOverflow) disse uma vez: “É mais difícil ler código do que escrevê-lo”. Por que isso é tão verdade? Parte do motivo são comentários ruins. Quando os desenvolvedores não comentam seu código, torna-se quase impossível decifrar o que está acontecendo. Mas com um roteiro sólido de comentários, esse miasma de código é muito mais fácil de entender.

Então, para aqueles que procuram ajudar seus desenvolvedores a melhorar seu trabalho, o que fazer e o que não fazer ao comentar código? Vamos dar uma olhada.

Use comentários como forma de comunicação

Uma das melhores coisas que você pode ajudar seus programadores a entender é que eles devem usar comentários como um meio de comunicar suas intenções e ações a outros programadores. Se um programador incluir comentários bem escritos em seu código, ele estará se comunicando com todos os seus colaboradores sobre o que está acontecendo em seu trabalho.

Escreva comentários com outra pessoa em mente

Na mesma linha, seus desenvolvedores devem considerar que os comentários devem ser escritos pensando em outras pessoas. Esta ferramenta não serve apenas para deixar anotações sobre seu trabalho, mas também para ajudar outras pessoas a decifrar o que fizeram.

Um dos principais objetivos dos comentários é ajudar outros programadores a entender o que está acontecendo no código. Isso significa que seus desenvolvedores devem escrever de forma que qualquer desenvolvedor possa abrir seu trabalho e entender o que está acontecendo.

Trabalhe para eliminar a confusão

Os comentários do código devem servir ao propósito de eliminar a confusão do código. Não se trata de exibir o seu trabalho, mas de simplificar o processo de colaboração e compreensão. Tornar seu trabalho claro e óbvio deve ser o objetivo número um dos comentários de código.

Isso também significa que os comentários do seu desenvolvedor também devem ser muito claros e concisos (e não adicionar ainda mais confusão ao mix).

Forneça links para a fonte original do código copiado

Se seus desenvolvedores copiarem código de outras fontes, eles deverão sempre deixar links para as fontes originais. Por que? Porque quem segue seus passos pode precisar entender por que usou aquele trecho de código e qual era sua intenção original, podendo até precisar entrar em contato com o desenvolvedor do código copiado.

Adicione comentários ao corrigir bugs

Os comentários de código não são apenas para código original (ou copiado), mas também para quando seus desenvolvedores corrigem bugs. Esses comentários devem explicar o que fizeram para corrigir o bug e por que isso foi necessário. Novamente, porém, seus desenvolvedores não devem escrever instruções extensas nos comentários, mas devem ser precisos e eficientes em suas palavras.

Faça uso de anotações ou tags de código

Para ajudar a tornar as coisas concisas, seus desenvolvedores devem usar anotações e tags de código. Por exemplo, @desc será uma descrição, @param será uma descrição de parâmetros, @returns descreverá a saída retornada e @throws descreverá possíveis tipos de erros. A maioria dos desenvolvedores deve ter um conhecimento sólido dessas anotações e tags. Caso contrário, certifique-se de que eles aprendam sobre eles.

Escreva comentários ao escrever seu código

Em vez de seus desenvolvedores voltarem após a conclusão do código para inserir comentários, eles devem escrevê-los à medida que avançam. Isso pode evitar muitos problemas. Primeiro, evitará que o desenvolvedor esqueça por que fez algo. Segundo, se algo acontecer a um desenvolvedor no meio do projeto, os comentários já estarão lá, para que alguém possa continuar de onde parou sem muitos problemas.

Não comente tudo

Também é importante que seus desenvolvedores entendam que não devem comentar sobre tudo. Os desenvolvedores não deveriam comentar o óbvio. Esse erro acontece muito com novos programadores que sentem que precisam documentar tudo o que criam ao longo do caminho.

Para ajudar com isso, peça aos seus desenvolvedores que considerem se o que estão escrevendo segue convenções e sintaxes amplamente aceitas, o que significa que provavelmente não precisa de comentários.

Não use comentários como substitutos da documentação

Comentários de código e documentação não são a mesma coisa. Você não quer que os desenvolvedores usem comentários como documentação porque o código pode acabar sendo muito longo (e confuso) e causar trabalho desnecessário. Isso acontece muito porque os desenvolvedores odeiam escrever documentação.

Os comentários do código existem para explicar funções e abordagens específicas, não para descrever como algo funciona em detalhes. Se seus desenvolvedores estão adicionando informações estranhas em seus comentários de código, você precisa interromper esse comportamento antes que fique fora de controle.

Não se refira a outros comentários em seus comentários

Se seus desenvolvedores estão se referindo a outros comentários (ou mesmo a outros documentos), eles estão dando aos outros desenvolvedores mais trabalho do que o necessário. Considere o seguinte: um desenvolvedor coloca um comentário no código que se refere a outro comentário. Isso significa que um desenvolvedor que segue essa pessoa terá que pesquisar o código para encontrar o comentário mencionado. Isso é muito trabalho.

Em vez de se referir a outro comentário, seu desenvolvedor deve explicar o que precisa dizer (e fazê-lo com eficiência). O objetivo deveria ser dar menos trabalho aos outros, e não mais.

Conclusão

Os comentários do código são tão importantes quanto o código real, porque ajudam a facilitar o trabalho de todos. Se você conseguir incutir bons hábitos de comentários em seus desenvolvedores desde o início, poderá ter certeza de que qualquer um poderá pegar o código de outro desenvolvedor e saber exatamente o que foi feito, por que foi feito e como foi feito.