Code Style: o seu estilo de escrever código

Duas perguntas aparecem em qualquer projeto. O cliente pergunta quanto custa mudar uma regra. O colega pergunta o que aquela função faz. Responder as duas exige abrir o código e narrar o que está escrito ali.

Quando cada arquivo segue uma convenção diferente, essa narração é improvisada, e sai diferente a cada vez que alguém pergunta. Quando o código segue uma convenção só, a resposta já está no arquivo: os nomes contam a sequência e quem escuta acompanha.

O Code Style é o guia onde documento as convenções, os padrões e as boas práticas que sigo. Está publicado em thiagocajadev.github.io/code-style, com o código-fonte no GitHub.

Conceitos fundamentais

Quem lê o seu código

O software é lido mais vezes do que é escrito, e cada leitor procura uma coisa diferente:

• O cliente quer saber o que o sistema faz e quanto custa mudar.
• O time quer alterar uma regra sem quebrar outras três.
• Quem entra amanhã quer entender o fluxo sem depender de você numa call.
• Você, daqui a seis meses, não vai lembrar por que escreveu daquele jeito.

Um code style responde essas perguntas pela mesma via: a mesma ideia aparece escrita do mesmo jeito em todo lugar. Assim, “onde mexo pra mudar o desconto?” se resolve em uma linha do arquivo, e não depende de quem está explicando.

Em time, a melhor abordagem é a convenção que a organização já definiu. O entendimento coletivo prevalece sobre a preferência pessoal, incluindo a minha.

Padrão, convenção e estilo

Escrevi sobre a diferença entre padrão e convenção em Convenções de Código, e sobre como isso aparece nas consultas ao banco em SQL com estilo. Padrão é norma. Convenção é acordo. O code style é o acordo aplicado linha a linha.

Boa parte do acordo é verificável por ferramenta. O EditorConfig alinha indentação e fim de linha entre editores diferentes. O linting transforma a convenção em erro de build. O que a ferramenta cobra sozinha, ninguém precisa cobrar na revisão, e a revisão fica livre pra discutir a regra de negócio.

Existe também o registro do que não fazer. Os anti-patterns são o catálogo de problemas que alguém já enfrentou antes de você.

Os princípios em três camadas

O guia organiza os princípios como um checklist de revisão, do mais amplo ao mais detalhado. A ordem permite parar em qualquer camada e ainda ter ganho.

A camada de Forma é a que mais ajuda na hora de explicar. Com o orquestrador no topo e as funções auxiliares abaixo dele, a primeira tela do arquivo já mostra a sequência de passos. Quem lê acompanha os nomes em ordem e desce nos detalhes só quando precisa.

Aprender pelo exemplo

A regra escrita explica e o código ao lado mostra. Por isso cada conceito do guia vem com dois exemplos. Abaixo está o mesmo cálculo de total de um pedido, escrito de duas formas.

function calc(d) {
  let r = 0;
  if (d != null) {
    if (d.items && d.items.length > 0) {
      for (let i = 0; i < d.items.length; i++) {
        r += d.items[i].p * d.items[i].q;
      }
      if (d.cupom == "PRIMEIRA") {
        r = r - r * 0.1;
      }
    }
  }
  return r > 0 ? r : 0;
}

Pra narrar essa função, você precisa decifrar antes o que são d, r, p e q. O 0.1 no meio do cálculo não diz que representa a primeira compra, e a regra de negócio está três níveis de indentação abaixo da assinatura.

// A chamada diz o que acontece, em uma linha.
const total = calculateOrderTotal(order);

// calculate-order-total.js
import { ValidationError } from "infra/errors.js";

const FIRST_ORDER_COUPON = "PRIMEIRA";
const FIRST_ORDER_DISCOUNT = 0.10;

function calculateOrderTotal(order) {
  const hasItems = order?.items?.length > 0;
  if (!hasItems) {
    throw new ValidationError({
      message: "O pedido não tem itens.",
      action: "Adicione ao menos um item antes de calcular o total.",
    });
  }

  const subtotal = sumItems(order.items);
  const total = applyFirstOrderDiscount(subtotal, order.coupon);
  return total;

  function sumItems(items) {
    let subtotal = 0;

    for (const item of items) {
      const itemTotal = item.price * item.quantity;
      subtotal += itemTotal;
    }

    return subtotal;
  }

  function applyFirstOrderDiscount(subtotal, coupon) {
    if (coupon !== FIRST_ORDER_COUPON) {
      return subtotal;
    }

    const discountedTotal = subtotal * (1 - FIRST_ORDER_DISCOUNT);
    return discountedTotal;
  }
}

A narração agora é a própria leitura, de cima para baixo. O nome da função diz o que ela entrega: o total do pedido. A primeira verificação barra o pedido sem itens na entrada, com um erro que diz o que houve e o que fazer. As três linhas seguintes contam o cálculo na ordem em que ele acontece: soma os itens, aplica o desconto de primeira compra, devolve o total.

Repare que o pedido vazio não volta como 0. Zero é um total legítimo, então devolvê-lo aqui obrigaria quem chama a adivinhar se o pedido estava vazio ou se os itens eram gratuitos. O erro tipado separa os dois casos, e o caminho de sucesso passa a ter um formato só: um número.

Os detalhes ficam abaixo, e você só desce até eles se quiser. sumItems e applyFirstOrderDiscount moram dentro da função que as chama, então a história inteira cabe em um bloco. O desconto de 10% virou FIRST_ORDER_DISCOUNT, então quando o marketing pedir 15%, você sabe qual linha muda e responde o prazo na própria reunião. O cálculo é o mesmo do exemplo anterior.

Um passo de cada vez

O site do Code Style publica as linguagens que mais uso, entre elas JavaScript, TypeScript, C# e SQL, mais os conceitos compartilhados (arquitetura, processo, qualidade, plataforma e IA). O repositório no GitHub guarda o guia completo, com as demais linguagens. Ler tudo de uma vez rende pouco, e mudar dez hábitos na mesma semana rende menos ainda.

Pegue um princípio e pratique com ele até virar automático. Sugiro esta ordem, mais rápido de aprender e com mais impacto:

1. Nomes expressivos. Troque o por order e t por total. Veja quantos comentários deixam de ser necessários.
2. Retorno antecipado. Saia da função na falha, e o else depois do return desaparece.
3. Sem valores mágicos. Cada número solto vira uma constante com nome fácil de entender e lembrar.
4. Funções pequenas. Uma responsabilidade, um nível de abstração. Mais fácil descrever o processo que o código trata.

Siga assim por diante a cada conceito aprendido.

Nada disso precisa ser estudado sozinho. Cole um princípio do guia no chat da sua IA favorita e peça pra ela revisar um arquivo seu contra aquela regra, um de cada vez. É uma forma honesta de aprender: você vê a regra aplicada ao seu próprio código, discute o caso em que ela não cabe e decide se adota.

O Code Style é público, sob licença CC BY 4.0, e a página dele sai do DoDocs. Se o seu estilo de código ou o do seu time é diferente, fica o convite: forke o repositório e escreva o acordo de vocês.

Bons estudos e bons códigos!

Referências

• Code Style, o site publicado: as linguagens que mais uso
• Code Style no GitHub: o guia completo, com as demais linguagens
• DoDocs, o gerador que publica o guia
• Convenções comuns em C#
• JavaScript Coding Conventions
• SQL Style Guide