Comentários no código – Vilões ou Mocinhos?

Comentários de código são ferramentas valiosas quando usados corretamente. Eles são especialmente úteis em algoritmos complexos e em situações onde o código não é autoexplicativo.

O contexto

O código deve ser autodocumentado, não há necessidade de comentários.

Como desenvolvedor, você já deve ter ouvido alguém de sua equipe dizer essa frase em algum momento, se não em muitos. É uma ideologia comum que muitos repetem, muitas vezes porque de fato é o pensamento a ser seguido, porém neste artigo quero abordar alguns casos de uso que enxergo como exemplos onde comentários no código podem contribuir positivamente na aplicação.

Disclaimer: Qual é a minha opinião?

Sinto que os comentários têm hora e lugar, especialmente com diferentes linguagens de programação. Obviamente, peço que não abuse dos comentários, eles em demasia, causam uma sujeira visual desnecessária e facilmente atrapalham a legibilidade e manutenabilidade do software. Concordo que os nomes de funções/métodos devem ser autoexplicativos e os desenvolvedores devem ser capazes de ler o código e saber aproximadamente o que é feito apenas folheando.

A recomendação aqui é utilizar comentários quando o código não é autoexplicativo (as vezes, o código é complexo e infelizmente não tão óbvio assim). Os “autodocumentadores” argumentariam que o código deveria ser escrito de uma forma que explicasse sua intenção sem os comentários, no entanto, acredito fortemente que os comentários explicam parte significativa do código quando se atinge uma complexidade inevitável.

Algoritmos complexos

Ao escrever métodos/funções que outras pessoas da equipe podem não conhecer ou realmente entender, os comentários podem ser extremamente úteis para explicar o funcionamento interno.

Em algoritmos complexos, como o exemplo do quicksort, os comentários ajudam a explicar a lógica por trás do código, como evitar loops infinitos e a escolha do pivô. No exemplo abaixo, usei comentários para explicar o importante
ifpara evitar um loop sem fim durante a recursão. 

public static int[] Quicksort(int[] array)
{
    // Caso base: arrays com 0 ou 1 elemento já estão ordenados
    if (array.Length <= 1) return array;

    int pivot = array[array.Length / 2]; // Escolher o elemento do meio como pivô
    var left = array.Where(x => x < pivot).ToArray(); // Elementos menores que o pivô
    var middle = array.Where(x => x == pivot).ToArray(); // Elementos iguais ao pivô
    var right = array.Where(x => x > pivot).ToArray(); // Elementos maiores que o pivô

    // Ordenar recursivamente os sub-arrays esquerdo e direito e concatenar os resultados
    return Quicksort(left).Concat(middle).Concat(Quicksort(right)).ToArray();
}

Soluções e Workarounds Não Óbvios

Comentários são úteis para explicar soluções temporárias ou workarounds em bibliotecas de terceiros. Eles também enriquecem ferramentas como o Intellisense com informações adicionais.

/// <summary>
/// Converte uma string de data no formato 'YYYY-MM-DD' para um objeto DateTime.
/// Esta solução garante que a data seja corretamente analisada independentemente do fuso horário do usuário.
/// </summary>
/// <param name="dateString">String de data no formato 'YYYY-MM-DD'.</param>
/// <returns>Um objeto DateTime representando a data fornecida às 00:00 UTC.</returns>
public static DateTime ParseToUtcDate(string dateString)
{
    var parts = dateString.Split('-').Select(int.Parse).ToArray();
    var date = new DateTime(parts[0], parts[1], parts[2], 0, 0, 0, DateTimeKind.Utc);

    if (date == default) throw new ArgumentException("Formato de data inválido. Formato esperado: YYYY-MM-DD.");

    return date;
}

Clarificar a Intenção ou Lógica de Negócio

Comentários ajudam a explicar decisões de lógica de negócio que podem não ser óbvias à primeira vista. Imagine no código abaixo, uma lógica ainda mais complexa, como:

• Usuário receber desconto por tempo de cadastro
• Descontos diferentes caso o usuário esteja via celular e/ou app
• Desconto em combinação de itens
• …. e muito mais

public void ApplyDiscount(User user)
{
    if (user.IsPremiumMember)
    {
        user.Discount = 0.2; // Membros premium recebem 20% de desconto
    }
    else
    {
        user.Discount = 0.0; // Não-membros premium não recebem desconto
    }
}

Maus exemplos de uso de comentários

Comentários redundantes: adicionar comentários que simplesmente não são necessários. Este é um exemplo perfeitamente bom de código autodocumentado, não há necessidade de comentários.

const addNumbers = (a: number, b: number): number => {
    // Adiciona a com b
    return a + b;
}

Comentários enganosos: adicionar comentários que fornecem informações enganosas

const multiplyNumbers = (a:number, b:number)=>{
  //Adiciona dois números
  return a * b;
}

Comentários excessivamente detalhados: Existe algo como escrever demais em seus comentários. Você deve tentar manter seus comentários diretos, sucintos e tão pequenos quanto possível.

/**
 * Esta função recebe dois argumentos, a e b, ambos números. Isso então
 * multiplica esses dois números usando o operador de multiplicação (*) e retorna
 * o resultado da multiplicação, que também é um número. Multiplicação é um
 * operação aritmética básica que combina dois números em um único produto.
 * Por exemplo, se a for 2 e b for 3, o resultado será 6.
 */
function multiply(a: number, b: number): number {
    return a * b;
}

Comentários inúteis:

Comentários inúteis não fornecem informações significativas, às vezes afirmando o óbvio ou incluindo notas triviais.

let count = 0; // Seta o contador para 0

function increment() {
    count++; // Incrementa o contador em +1
}

Notas pessoais, opiniões e linguagem imprópria

Incluir notas ou opiniões pessoais nos comentários não é profissional e inútil.

// Eu tentei tantas vezes fazer isso funcionar, esse foi o
// melhor que pude fazer.
const computeFactorial = (n: number): number => {
// Isso é estúpido, mas funciona...
    if (n <= 1) return 1;
    return n * computeFactorial(n - 1);
}

Conclusão

Sou um defensor do uso estratégico de comentários em códigos modernos. Os comentários desempenham um papel fundamental no fornecimento de contexto e no esclarecimento de lógicas complexas que podem não ser imediatamente óbvias. Porém, antes de escrever qualquer comentário, tente não escrevê-lo, acredito que antes de mais nada, o desenvolvedor deve colocar energia para o código ser sim, autodocumentável.

Aqui estão algumas práticas recomendadas para comentar no código:

1. Use nomenclatura descritiva: escolha variáveis, métodos e classes bem nomeados para minimizar a necessidade de comentários. Nomes claros muitas vezes reduzem a necessidade de explicações adicionais.
2. Escreva código claro: certifique-se de que seu código seja lógico e bem estruturado. Um bom design de código deve facilitar aos desenvolvedores a compreensão do propósito e do fluxo com base em nomes de variáveis ​​e tipos de retorno.
3. Forneça comentários intencionais: use comentários breves para explicar o propósito e a lógica por trás de códigos complexos ou não óbvios. Concentre-se no “porquê” e não no “o quê”.
4. Evite comentários excessivos: Não comente tudo só por comentar. Concentre-se nas áreas onde os comentários agregam valor real.
5. Ignorar Humor: Evite usar comentários humorísticos em seu código. Embora possam ser divertidos, não são profissionais e ocupam um espaço valioso.

Se um comentário ajudar a esclarecer seu processo de pensamento ou a intenção do código, outras pessoas provavelmente também se beneficiarão com ele.

Embora buscar um código autodocumentado seja uma boa prática, os comentários são essenciais para fornecer contexto, explicar lógica complexa e documentar soluções alternativas. Eles preenchem a lacuna entre a funcionalidade do código e sua finalidade, facilitando a compreensão, manutenção e extensão da base de código.