Clean Code: Escrevendo Código que Outros (e Você no Futuro) Vão Amar Ler

Leia um jornal: o título entrega a essência, o primeiro parágrafo detalha, o restante traz suporte. Seu código deve funcionar igual — funções de alto nível no topo, implementação abaixo.

// MANCHETE: o que este módulo faz?export function processUserOrder(userId, orderId) {  const user = getUser(userId);  const order = getOrder(orderId);  validateOrder(user, order);  return chargeAndShip(user, order);} // DETALHES: como ele faz?function getUser(userId) { /* ... */ }function getOrder(orderId) { /* ... */ }function validateOrder(user, order) { /* ... */ }function chargeAndShip(user, order) { /* ... */ }

Leia de cima para baixo. O o quê vem antes do como — nunca enterre a intenção principal no fundo de uma função de 200 linhas.

Nomes estão em todo lugar: variáveis, funções, classes, arquivos. Bons nomes tornam comentários desnecessários.

Pronunciáveis e buscáveis:

// ❌ O que isso significa?const yyyymmdstr = moment().format('YYYY/MM/DD'); // ✅ Cristalinoconst currentDate = moment().format('YYYY/MM/DD');

Mesma palavra para o mesmo conceito — se você busca usuários com getUser(), não tenha também fetchClient() e retrieveCustomer().

Evite mapeamento mental — variáveis de uma letra forçam o leitor a lembrar o que l significa cinquenta linhas depois. Prefira location.

Sem contexto redundante — se a classe se chama Car, use make, model, color — não carMake, carModel.

A regra mais importante do código limpo — SRP (Single Responsibility Principle). Como Robert C. Martin afirma em Clean Code: "uma função deve fazer uma coisa, fazê-la bem e fazê-la apenas."

// ❌ Faz coisas demaisfunction emailClients(clients) {  clients.forEach(client => {    const record = database.lookup(client);    if (record.isActive()) email(client);  });} // ✅ Cada função, um trabalhofunction emailActiveClients(clients) {  clients.filter(isActiveClient).forEach(email);}function isActiveClient(client) {  return database.lookup(client).isActive();}

Limite parâmetros — dois ou menos é o ideal. Para mais, use objeto com destructuring:

createMenu({ title: 'Settings', body: 'User preferences', cancellable: true });

Não use flags booleanas — sinal de que a função faz mais de uma coisa. Divida em createFile() e createTempFile().

Literais inexplicáveis tornam o código difícil de entender e de alterar.

// ❌ O que é 86400000? Por que 18?setTimeout(blastOff, 86400000);if (user.age > 18) allowAccess(); // ✅ Constantes nomeadasconst MILLISECONDS_PER_DAY = 60 * 60 * 24 * 1000;const MINIMUM_LEGAL_AGE = 18;const STATUS = { ACTIVE: 1, INACTIVE: 0 }; setTimeout(blastOff, MILLISECONDS_PER_DAY);if (user.age > MINIMUM_LEGAL_AGE) allowAccess();

Dica: a regra no-magic-numbers do ESLint sinaliza números mágicos automaticamente.

Código duplicado significa múltiplos lugares para atualizar quando a lógica muda. Andy Hunt e Dave Thomas em The Pragmatic Programmer: "cada fragmento de conhecimento deve ter uma única representação autoritária."

// ✅ Unificado com tratamento específicofunction showEmployeeList(employees) {  employees.forEach(employee => {    const baseData = {      salary: employee.calculateSalary(),      experience: employee.getExperience(),    };    const extraData = employee.type === 'developer'      ? { githubLink: employee.getGithubLink() }      : { portfolio: employee.getPortfolio() };    render({ ...baseData, ...extraData });  });}

Cuidado: uma abstração ruim é pior que duplicação. Só abstraia quando você vê um padrão claro.

Efeito colateral = fazer algo além de receber inputs e retornar outputs: mutar global, escrever arquivo, mutar parâmetro de entrada.

// ❌ Muta o array originalfunction addItemToCart(cart, item) {  cart.push({ item, date: Date.now() });} // ✅ Retorna novo arrayfunction addItemToCart(cart, item) {  return [...cart, { item, date: Date.now() }];}

Funções puras são previsíveis e fáceis de testar. Aprofunde em Pure Functions.

Código profundamente aninhado é difícil de acompanhar. Trate casos de borda primeiro:

// ❌ Aninhadofunction getPayAmount(employee) {  let result;  if (employee.isSeparated) {    result = { amount: 0, reason: 'separated' };  } else if (employee.isRetired) {    result = { amount: 0, reason: 'retired' };  } else {    result = { amount: calculateSalary(employee), reason: 'employed' };  }  return result;} // ✅ Guard clausesfunction getPayAmount(employee) {  if (employee.isSeparated) return { amount: 0, reason: 'separated' };  if (employee.isRetired) return { amount: 0, reason: 'retired' };  return { amount: calculateSalary(employee), reason: 'employed' };}

Em loops, use continue para pular iterações em vez de aninhar if dentro de if.

Bom código se documenta sozinho. Comentários explicam por quê, não o quê. Se precisa de comentário para explicar o que o código faz, reescreva o código.

Não afirme o óbvio — // Loop por cada caractere não acrescenta nada.

Delete código morto — código comentado é lixo. O git lembra.

Não use comentários como controle de versão — // 2016-12-20: Removed monads pertence ao histórico do git, não ao arquivo.

S — Single Responsibility: UserSettings não deve verificar credenciais e alterar configurações — separe UserAuth de UserSettings.

O — Open/Closed: estenda adicionando classes (Circle, Rectangle com getArea()), não modificando if/else gigantes.

L — Liskov Substitution: Square extends Rectangle quebra quando setWidth/setHeight têm semânticas diferentes — prefira classes separadas.

I — Interface Segregation: torne features opcionais (animationModule?) em vez de exigir tudo no construtor.

D — Dependency Inversion: injete dependências — new InventoryRequester() dentro da classe acopla; passe requester no construtor.

No monorepo Alamino, MVC + SOLID guiam cada app — detalhes em Design Patterns e na documentação do projeto.

Funções que fazem uma coisa sem efeitos colaterais são fáceis de testar. Se é difícil de testar, provavelmente faz coisas demais ou tem dependências ocultas.

// ❌ Difícil — mockar sendEmail, logActivity, updateDatabasefunction processUser(user) {  if (user.email.includes('@')) {    sendEmail(user.email);    logActivity(user);    updateDatabase(user);  }} // ✅ Trivial de testarfunction isValidEmail(email) {  return email.includes('@');}

Regra: uma função, uma responsabilidade, sem side effects = teste trivial.

Parabéns! Você completou o nono e último conceito da trilha Advanced Topics — e toda a série 33 Conceitos JS publicada neste portfólio.

Conecte clean code com Error Handling (erros legíveis), Modern JS Syntax (features que simplificam leitura) e Design Patterns (soluções reutilizáveis).

→ Revise o catálogo completo em 33 Conceitos JS — trilhas, busca e filtros interativos.

→ E agora?

A jornada continua no Beyond 33 — 29 conceitos avançados em 9 categorias. Leia a visão geral e explore a trilha em Beyond 33. Os artigos individuais serão publicados gradualmente.

→ Referência adaptada: clean-code-javascript (Ryan McDermott) — 94k+ estrelas no GitHub.

Fonte de referência: 33jsconcepts.com/concepts/clean-code ⬀