22

Após ler um pouco do livro Clean Code de Robert C. Martin, ele diz que não adianta "maquiar" um código ruim com comentários, em outras palavras, tentar explicar uma gambiarra feita ali.

Também é citado sobre explique o que você quer fazer no seu código com seu código e não use comentários para isso.; seguido do exemplo que isso:

if (employee.isEligibleForFullBenefits())

é melhor que isto:

// Verifica se o empregado é elegível aos benefícios
if ((employee.flags & HOURLY_FLAG)
     && (employee.age > 65)) 

Em adição a esta resposta, onde é escrito como escrever um código limpo e de fácil manutenção, o código abaixo:

public bool ValidacaoCPF(int[] cpf)
{
    int DV1 = 0, DV2 = 0, aux = 10;

    if (!cpf.All(x => x == cpf.First())) //Verifica se todos os números são iguais
        if (cpf[9] == ((DV1 = (cpf.Take(9).Sum(x => (x * aux--)) % 11)) < 2 ? 0 : 11 - DV1)) //Cálculo do primeiro digito verificador
            return cpf[10] == (((aux = 11) * 0) + (DV2 = (cpf.Take(10).Sum(x => (x * aux--)) % 11)) < 2 ? 0 : 11 - DV2); //Cálculo do segundo digito verificador

    return false;
}

Passou a ser isso:

if (!cpf.All(x => x == cpf.First())) //Verifica se todos os números são iguais

    //Cálculo do primeiro digito verificador
    if (cpf[9] == (
        (DV1 = (
            cpf.Take(9).Sum(x => (x * aux--)) % 11
        )) < 2 ? 0 : 11 - DV1
    )) 
    {
        //Cálculo do segundo digito verificador
        aux = 11;
        return cpf[10] == (
          (DV2 = (  cpf.Take(10).Sum(x => (x * aux--)) % 11  )) < 2 ? 
          0 : 
          11 - DV2);
    }

Por mim, não teve quase nenhuma mudança significativa, apenas está tentando explicar algo que não entenderia se não tivesse aqueles comentários ali. Logo então, se encaixa num código sujo para mim.

Em outras palavras, foi usado comentários para explicar algo que não entenderíamos ora senão pela existência dos mesmos ali.

Por suma, os comentários realmente sujam o código ao invés de limpá-los? Onde devemos usá-los e quando devemos evitá-los?

Informações retiradas da página 86 e 87 do livro citado acima.

2
  • 1
    Comentários são muito uteis para documentação, principalmente de linguagens fracamente tipadas, por exemplo, você consegue explicar melhor pra que serve tal método e o que ele precisa
    – Costamilam
    Commented 23/07/2019 às 19:25
  • 2
    Um dos pontos que ele faz dos comentários é que tem tendência a não serem atualizados com as alterações de código, o que os torna mentirosos e enganam o leitor. Isso seria mais um fator para fazer apenas os comentários realmente necessários e não sair comentando tudo o que é linha.
    – Isac
    Commented 23/07/2019 às 21:49

4 Respostas 4

23

O Uncle Bob tem um jeito de fazer e pode não ser o mais adequado para todos, ele tem contexto dele, você tem o seu e eu tenho o meu. Você deve achar o que é mais adequado para você e para seu time. Os livros dele e de muita gente são bons para te fazer pensar, não para dar receitas de bolo de como se codifica ou desenvolve software. O livro dele é cheio de afirmações não muito claras (isso é mais ou menos normal em tudo que você for ler) e cabe a você interpretar o que está escrito ou até questionar se é realmente 100% válido, geralmente não é tanto quanto está escrito, ainda que não seja um erro.

Este item em específico é um bom conselho, mas não pode ser levado ao extremo, tem caso que você complica demais o código para evitar o comentário.

Se você seguir outro ponto dele que é ter métodos pequenos (ele erra quando fala em número de linhas, chega ser ingênuo) o código será legível por outros méritos, precisará de poucos comentários e não precisará ser tão descritivo assim (não estou dizendo que não precise ser descritivo). Eu até mostro na resposta à pergunta linkada que muitas vezes a gente não pára para pensar que tem coisas bem legíveis e pouco descritivas porque estamos muito acostumados, o espírito da coisa está ali. Também achei que o código do mgibsonbr acrescentou muito pouco, se fosse pra melhorar teria que fazer mais abstrações e não mais comentários ou quebrar linha. Pode ter melhorado, mas não muito.

Há casos que fazer uma abstração (seu primeiro exemplo) é melhor que escrever o código que faz o que deseja (seu segundo exemplo), mas não tome isso como verdade sempre.

Tem uma pergunta sobre Como saber a medida certa de comentários?. Falo sobre anti pattern quando começa por informação demais no código. Tudo tem motivo, não é regra boba inventada.

Eu falo sobre o comentário violar o DRY. Só tome cuidado para não achar que isso é uma regra.

Nomenclatura pode ajudar tornar o código mais descrito.

Técnicas de scaffolding podem ajudar (abstração sem custo de processamento).

Escolher o estilo de codificação pode ajudar ter códigos mais corretos e declarativos.

Mas cuidado, abstração demais, além de potencialmente deixar o código mais lento, pode esconder coisas importantes. E é muito fácil fazer o nível errado. Não pode nem vazar abstração, nem exagerar.

A regra básica é comentar o porquê das coisas, o que não pode ser expressado em código, mas não exagerar nisso. Só a experiência qualitativa (não adianta fazer errado por 20 anos que isso não é experiência) faz você acertar o ponto, não tenta regra mágica. Por isso é bom sempre ter bons mentores (não é coaching :D) mas ir orientando se está certo ou não no caso concreto. A internet ajuda nisso, mas tem que tomar cuidado e criar sua própria mentalidade aos poucos.

Se você comentar o que fica realmente mais bem expressado em código suja sim.

Coloquei no GitHub para referência futura.

7

Não tem motivo definitivo para não usar comentários. Existem recomendações. Você tem que se perguntar se realmente é útil coloca-los ou se apenas está adicionando ruído no código que irão gerar mais distração do que orientação.

Comentários estão disponíveis em todas as linguagens e são úteis sim, mas como tudo, eles também devem ser usados com parcimônia.

A intenção do autor ao ser contrário ao uso de comentários tem como objetivo justamente causar a reflexão. Você realmente precisa adicionar esse comentário para explicar o código? Você realmente precisa transformar um trecho de código em comentário só para o compilador ignorá-lo sem perder o histórico do código antigo? E por ai vai.

Na maioria das vezes era melhor ter usado bons nomes, levado em consideração padrões e boas práticas, enfim, pensado um pouco mais na arquitetura ou na modelagem, do que complicar um código e depois tentar explicar através de comentários.

Exemplos como esse:

// Verifica se o empregado é elegível aos benefícios
if ((employee.flags & HOURLY_FLAG)
     && (employee.age > 65)) 

Não são ruins por usar comentários e sim por violar padrões como DRY ou a Lei de Demeter. Ao expor detalhes de regras de validação que são de responsabilidade do objeto employee e que induzem à duplicação de código, pois, provavelmente iriam se repetir em mais lugares onde essa validação fosse necessária.

O segundo exemplo dado, na minha opinião também ainda contém Code Smells e não precisaria de comentários, pois está sobrecarregado de responsabilidades, violando o primeiro princípio SOLID.

public bool ValidaCpf(int[] cpf)
{
    int DV1 = 0, DV2 = 0, aux = 10;

    if (!cpf.All(x => x == cpf.First())) //Verifica se todos os números são iguais

        //Cálculo do primeiro digito verificador
        if (cpf[9] == (
            (DV1 = (
                cpf.Take(9).Sum(x => (x * aux--)) % 11
            )) < 2 ? 0 : 11 - DV1
        ))
        {
            //Cálculo do segundo digito verificador
            aux = 11;
            return cpf[10] == (
                (DV2 = (cpf.Take(10).Sum(x => (x * aux--)) % 11)) < 2 ?
                0 :
                11 - DV2);
        }

    return false;
}

Ao ser refatorado poderia ficar assim:

public bool ValidaCpf(int[] cpf)
{
    return !saoTodosNumerosIguais(cpf) && digitoEhValido(cpf, 10) && digitoEhValido(cpf, 11);
}

private bool saoTodosNumerosIguais(int[] cpf)
{
    return cpf.All(x => x == cpf.First());
}

private bool digitoEhValido(int[] cpf, int posicao)
{
    int dv = 0;
    return cpf[posicao - 1] == ((dv = (cpf.Take(posicao - 1).Sum(x => (x * posicao--)) % 11)) < 2 ? 0 : 11 - dv);
}

Até que ponto você quer ir é subjetivo. Mas a lição passada pelo livro Clean Code é muito boa e vale muito pela reflexão. Veja, o quanto nós refletimos sobre o primeiro código até evoluí-lo para modelos de "maior qualidade", mais fácil de ser testado unitariamente ao mesmo tempo que exercitamos nossa forma de pensar sobre a solução gerada, simplesmente questionando a necessidade de comentar o código!

7

Uma forma que eu aprendi onde eu trabalho é deixar bem claro o nome das variáveis pro que eu quero fazer.

Isso já evita muitos comentários desnecessários.

Vou dar um exemplo:

    foreach (var perfilDoUsuario in listaDePerfisDoUsuario)
            {
                if (perfilDoUsuario.Value.ToUpper().Contains((ListaDePerfisDoRelatorio.Gerente).ObterDescricao().ToUpper()))
                {
                    listaDeTiposDePerfis.Remove((int)ListaDePerfisDoRelatorio.Gerente);
                    listaDeTiposDePerfis.Remove((int)ListaDePerfisDoRelatorio.Administrador);
                }
            }

Nesse trecho aí eu deixo bem claro quais perfis eu que quero remover da lista que eu tenho.

Claro que isso não deixa absolutamente explicado o porquê de eu ter feito isso, mas já ajuda um pouco.

Antigamente eu colocava o número direto do perfil, sem identificá-lo.

É só uma dica adicional.

5

Bons nomes tornam alguns comentários desnecessários

Quando o autor diz para não comentar o código, ele se refere a priorizar um código legível que não precisa de explicações redundantes através da adição de comentários. Nenhuma regra deve ser seguida cegamente, pois tudo depende de um contexto.

Os comentários têm o seu uso, o problema é quando eles são repetitivos ou são uma muleta para adicionar legibilidade a um código que é confuso e não possui bons nomes. Por exemplo, o código a seguir adiciona uma linha em um arquivo:

// Função que adiciona uma linha em um arquivo.
function add(string $name, string $string): void{
       
    file_put_contents($name, $string, FILE_APPEND);

}

Como é possível notar, o comentário deixa mais claro o que o código está fazendo. Nesse caso não seria necessário comentar se o código tivesse um nome melhor:

function addLineOnFile(string $filename, string $line): void{
       
    file_put_contents($filename, $line, FILE_APPEND);

}

Quando o código tem um bom nome, comentários como esses não são necessários porque o nome já diz tudo, entretanto isso não significa que comentar é errado e que isso deve ser seguido em todas as situações de forma dogmática como se fosse uma regra rigida.

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .