Self-Documenting Code: como escrever código limpo e legível

O conceito de self-documenting code é essencial. Em outras palavras, ele permite escrever código limpo, legível e sustentável. Além disso, quando o código se explica sozinho, a complexidade diminui e a manutenção melhora.

O verdadeiro diferencial está na clareza. Por isso, o código precisa ser compreensível ao longo do tempo. Dessa forma, você reduz a dependência de documentação externa.

Self-Documenting Code: código legível, sustentável e orientado à intenção

Nesse contexto, o self-documenting code consiste em escrever código que comunica bem. Ou seja, trata-se de um código que:

Dispensa explicações externas sempre que possível
Comunica intenção, não apenas implementação
Reduz a necessidade de comentários desnecessários

Em outras palavras, a ideia é simples: o código deve ser a documentação.

Segundo a definição de self-documenting code, o código deve ser compreensível sem depender de documentação externa.

Além disso, Robert C. Martin, em Clean Code, afirma que comentários podem indicar problemas:

“Comentários são falhas no código. Se você precisa comentar, talvez o código não esteja claro o suficiente.”

Quando o código é difícil de entender, surgem vários problemas. Por exemplo:

Aumenta o custo mental de manutenção
Dificulta evolução e refatoração
Além disso, compromete a escalabilidade

Portanto, escrever código claro não é apenas estética. Na prática, é engenharia de longo prazo.

Exemplos práticos de self-documenting code em C#

1. Nomes significativos

Ruim:

var x = d * 0.85;

Bom:

decimal discountedPrice = originalPrice * 0.85m;

Uso de tipos explícitos melhora leitura
Além disso, evita ambiguidade de tipo

2. Responsabilidade única (SRP)

Ruim:

public void ProcessUser(User user)
{
    Validate(user);
    Save(user);
    SendEmail(user);
}

Bom:

public void ValidateUser(User user) { }
public void SaveUser(User user) { }
public void SendWelcomeEmail(User user) { }

Assim, cada método tem uma responsabilidade clara. Como resultado, o código fica mais fácil de testar.

3. Código claro vs comentários

Em muitos casos, comentários são desnecessários. Isso acontece porque o próprio código já comunica sua intenção.

// Increment the counter
counter++;

4. Estrutura expressiva

public void DoStuff(List<User> u)
{
    foreach (var x in u)
    {
        if (x.A)
        {
            // ...
        }
    }
}

public void ProcessActiveUsers(List<User> users)
{
    foreach (var user in users)
    {
        if (user.IsActive)
        {
            ProcessUser(user);
        }
    }
}

Nesse caso, nomes claros tornam o fluxo mais compreensível. Dessa forma, o comportamento fica previsível.

5. Evitar código “esperto” (clever code)

return x && y || z;

if (x)
{
    return y;
}
return z;

Embora o código compacto pareça eficiente, ele reduz a clareza. Por isso, versões mais explícitas são melhores.

Veja também: ETL e desempenho em aplicações

Conclusão

O self-documenting code melhora a legibilidade e reduz erros. Além disso, facilita a manutenção.

Em resumo, código é comunicação entre humanos. Portanto, clareza deve ser prioridade.

Seu código será lido muito mais vezes do que será escrito.

Self-Documenting Code: como escrever código limpo e legível na prática