Regra
Evite arquivos excessivamente grandes.
Arquivos grandes com múltiplas responsabilidades
são difíceis de manter.
Linguagens suportadas: 45+Introdução
Arquivos com milhares de linhas geralmente lidam com múltiplas preocupações não relacionadas, tornando difícil localizar funcionalidades específicas. Um de 3000 linhas utils.js arquivo contendo auxiliares de validação, formatação de strings, manipulação de datas e utilitários de API força os desenvolvedores a rolar por código não relacionado para encontrar o que precisam. Arquivos grandes também criam conflitos de merge à medida que múltiplos desenvolvedores modificam diferentes seções simultaneamente.
Por que isso importa
Manutenibilidade do código: Arquivos grandes misturam funcionalidades não relacionadas, exigindo que os desenvolvedores entendam centenas de linhas de código irrelevante para modificar uma única função. Encontrar uma lógica específica se torna um exercício de busca em vez de navegar para um arquivo com nome apropriado.
Conflitos de controle de versão: Quando múltiplos desenvolvedores trabalham em diferentes funcionalidades no mesmo arquivo grande, conflitos de merge ocorrem frequentemente. Arquivos menores e focados permitem o desenvolvimento paralelo, pois cada desenvolvedor trabalha em arquivos separados.
Eficiência da revisão de código: Revisar alterações em arquivos grandes exige mais contexto. Os revisores devem entender como as modificações afetam outros códigos não relacionados no mesmo arquivo. Arquivos menores tornam o escopo das alterações óbvio, acelerando as revisões.
Exemplos de código
❌ Não-conforme:
// utils.js (mais de 1500 linhas)
function validateEmail(email) { /* ... */ }
function validatePhone(phone) { /* ... */ }
function formatCurrency(amount) { /* ... */ }
function formatDate(date) { /* ... */ }
function parseJSON(str) { /* ... */ }
function apiRequest(url) { /* ... */ }
function debounce(fn, delay) { /* ... */ }
function throttle(fn, limit) { /* ... */ }
// ... mais de 100 funções não relacionadas
Por que está errado: Um único arquivo massivo contém validação, formatação, parsing, chamadas de API e utilitários de desempenho. Encontrando debounce() Exige rolar por centenas de funções não relacionadas. Múltiplas equipes modificando este arquivo criam conflitos de merge constantes.
✅ Compatível:
// validation/email.js
export function validateEmail(email) { /* ... */ }
// validation/phone.js
export function validatePhone(phone) { /* ... */ }
// formatting/currency.js
export function formatCurrency(amount) { /* ... */ }
// formatting/date.js
export function formatDate(date) { /* ... */ }
// api/request.js
export function apiRequest(url) { /* ... */ }
// performance/debounce.js
export function debounce(fn, delay) { /* ... */ }
Por que isso importa: Cada função utilitária em um arquivo dedicado dentro de diretórios categorizados. Encontrando debounce() significa navegar para performance/debounce.js diretamente. Equipes trabalhando em diferentes utilitários não entram em conflito porque estão em arquivos separados.
Conclusão
Mantenha os arquivos com menos de 500 linhas, sempre que possível. Quando os arquivos excederem esse limite, procure por responsabilidades distintas que possam ser extraídas para módulos separados. Organize arquivos relacionados em diretórios para manter a estrutura, enquanto mantém arquivos individuais focados e de fácil manutenção.
