Regra
Uma classe por arquivo.
Múltiplas classes em um único arquivo tornam a
organização do código pouco clara e mais difícil de navegar.
Linguagens suportadas: 45+Introdução
Colocar múltiplas classes em um único arquivo dificulta a localização de classes específicas ao navegar por uma base de código. Desenvolvedores procurando por UserRepository não o encontrará rapidamente se estiver enterrado em um arquivo chamado database.js juntamente com outras cinco classes. Isso viola o princípio da menor surpresa e retarda o desenvolvimento, pois os membros da equipe perdem tempo procurando por definições de classe.
Por que isso importa
Manutenibilidade do código: Múltiplas classes por arquivo criam limites pouco claros entre as responsabilidades. Quando uma classe precisa de modificação, os desenvolvedores devem abrir um arquivo contendo classes não relacionadas, aumentando a carga cognitiva e o risco de modificar acidentalmente o código errado.
Navegação e descoberta: IDEs e editores de texto têm dificuldade em fornecer um "ir para a definição" preciso quando múltiplas classes compartilham um arquivo. Desenvolvedores gastam tempo procurando dentro dos arquivos em vez de pular diretamente para a classe de que precisam. Isso se agrava em grandes bases de código com centenas de classes.
Conflitos de controle de versão: Quando múltiplas classes compartilham um arquivo, alterações em classes diferentes por desenvolvedores diferentes criam conflitos de merge. Arquivos separados permitem o desenvolvimento paralelo sem sobrecarga de coordenação, pois cada desenvolvedor trabalha em seu próprio arquivo.
Exemplos de código
❌ Não-conforme:
// database.js
class UserRepository {
async findById(id) {
return db.users.findOne({ id });
}
}
class OrderRepository {
async findByUser(userId) {
return db.orders.find({ userId });
}
}
class ProductRepository {
async findInStock() {
return db.products.find({ stock: { $gt: 0 } });
}
}
module.exports = { UserRepository, OrderRepository, ProductRepository };
Por que está errado: Três classes de repositório não relacionadas em um arquivo chamado database.js. Procurando por OrderRepository exige saber que está em database.js em vez de OrderRepository.js. Alterações de arquivo afetam múltiplas classes, criando conflitos de merge desnecessários.
✅ Compatível:
// UserRepository.js
class UserRepository {
async findById(id) {
return db.users.findOne({ id });
}
}
module.exports = UserRepository;
// OrderRepository.js
class OrderRepository {
async findByUser(userId) {
return db.orders.find({ userId });
}
}
module.exports = OrderRepository;
// ProductRepository.js
class ProductRepository {
async findInStock() {
return db.products.find({ stock: { $gt: 0 } });
}
}
module.exports = ProductRepository;
Por que isso importa: Cada classe em seu próprio arquivo torna a navegação previsível. IDEs podem pular diretamente para OrderRepository.js ao procurar pela classe. Alterações em um repositório não afetam outros, eliminando conflitos de merge desnecessários.
Conclusão
Nomeie os arquivos de acordo com a classe que contêm para uma navegação previsível. Essa convenção se adapta a grandes bases de código onde encontrar classes específicas rapidamente é importante. Os arquivos adicionais valem a clareza organizacional que proporcionam.
