Close Menu
Código Simples .NETCódigo Simples .NET
    Facebook X (Twitter) Instagram
    Trending
    • NewSQL em 2025: O Estado Atual, Tendências e o Futuro dos Bancos de Dados Relacionais Escaláveis
    • 12 Regras Essenciais para Reduzir a Latência de Aplicações
    • Cache Hit Ratio: Como uma Simples Métrica Pode Revolucionar sua Arquitetura
    • Como a Uber calcula o tempo estimado de chegada
    • 30 APIs Gratuitas para desenvolvedores
    • Por que escalar escrita é tão mais difícil do que escalar leitura?
    • MongoDB Analyzer para .NET: Visualize e otimize suas consultas de forma simples
    • Cardinalidade: O Conceito que Transforma o Desempenho de Bancos de Dados SQL e NoSQL
    Facebook X (Twitter) Instagram
    Código Simples .NETCódigo Simples .NET
    Código Simples .NETCódigo Simples .NET
    Home»Boas práticas»Comentários no código – Vilões ou Mocinhos?

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

    Jhonathan SoaresBy Jhonathan Soares24 de julho de 20246 Mins Read Boas práticas
    Share
    Facebook Twitter LinkedIn WhatsApp Copy Link

    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.

    Share. Facebook Twitter LinkedIn Telegram WhatsApp Copy Link
    Jhonathan Soares
    • Website
    • Facebook
    • X (Twitter)
    • LinkedIn

    Criador do blog Código Simples e com mais 15 anos de experiência em TI, com títulos de MVP Microsoft na área de Visual Studio Development, Neo4j Top 50 Certificate, Scrum Master e MongoDB Evangelist.

    Posts Relacionados

    Como escolher bibliotecas para seu projeto: Uma análise crítica de dependências

    Boas práticas 20 de setembro de 20245 Mins Read

    Boas práticas de criação, armazenamento e validação de senhas em .NET

    Asp.net Boas práticas 9 de julho de 20248 Mins Read

    O Impacto das Interrupções no trabalho e como mitigá-las

    Gestão & Produtividade 17 de junho de 20245 Mins Read
    Newsletter

    Digite seu endereço de e-mail para receber notificações de novas publicações por e-mail.

    Junte-se a 25mil outros assinantes
    Posts recentes
    • NewSQL em 2025: O Estado Atual, Tendências e o Futuro dos Bancos de Dados Relacionais Escaláveis
    • 12 Regras Essenciais para Reduzir a Latência de Aplicações
    • Cache Hit Ratio: Como uma Simples Métrica Pode Revolucionar sua Arquitetura
    • Como a Uber calcula o tempo estimado de chegada
    • 30 APIs Gratuitas para desenvolvedores
    Categorias
    • Arquitetura (14)
      • Testes (2)
    • Asp.net (120)
      • C# (89)
      • Mvc (13)
    • Banco de dados (90)
      • NoSql (58)
      • Sql (38)
    • Boas práticas (29)
      • Gestão & Produtividade (1)
      • Metodologias Ágeis (6)
    • Cursos (52)
    • Dicas (105)
    • Front-End (92)
    • IA (1)
    • Linux (6)
    • NodeJS (4)
    • Post do Leitor (9)
    • Python (5)
    • Seo (12)
    • Tecnologia (30)
      • ITIL (1)
      • Padrões de Projeto (4)
    • Testes (2)

    VEJA TAMBÉM

    Cursos
    12 de fevereiro de 20166 Mins Read

    1000 livros gratuitos sobre programação!

    Olha que dica bacana! A pagina só com livros sobre programação é mantida no GitHub…

    30 APIs Gratuitas para desenvolvedores

    Facebook X (Twitter) Instagram LinkedIn

    Type above and press Enter to search. Press Esc to cancel.

    Vá para versão mobile