Regra

Evitar demasiado grandes ficheiros.
Os ficheiros ficheiros com múltiplas responsabilidades
são difíceis de manter.

Línguas suportadas: 45+

Introdução

Os ficheiros com milhares de linhas tratam normalmente de vários assuntos não relacionados, o que dificulta a localização de uma funcionalidade específica. Um ficheiro de 3000 linhas utils.js contendo auxiliares de validação, formatação de cadeias de caracteres, manipulação de datas e utilitários API obriga os programadores a percorrerem código não relacionado para encontrarem o que precisam. Os ficheiros grandes também criam conflitos de fusão, uma vez que vários programadores modificam diferentes secções em simultâneo.

Porque é importante

Manutenção do código: Os ficheiros grandes misturam funcionalidades não relacionadas, exigindo que os programadores compreendam centenas de linhas de código irrelevante para modificar uma função. Encontrar uma lógica específica torna-se um exercício de pesquisa em vez de navegar para um ficheiro com o nome adequado.

Conflitos de controlo de versões: Quando vários programadores trabalham em diferentes funcionalidades no mesmo ficheiro grande, os conflitos de fusão ocorrem frequentemente. Ficheiros mais pequenos e focados permitem um desenvolvimento paralelo, uma vez que cada programador trabalha em ficheiros separados.

Eficiência da revisão de código: A revisão de alterações em ficheiros grandes requer mais contexto. Os revisores devem entender como as modificações afetam outros códigos não relacionados no mesmo arquivo. Os ficheiros mais pequenos tornam o âmbito das alterações óbvio, acelerando as revisões.

Exemplos de código

Não conforme:

// utils.js (1500+ linhas)
função validateEmail(email) { /* ... */ }
função validatePhone(phone) { /* ... */ }
função formatCurrency(montante) { /* ... */ }
função formatDate(data) { /* ... */ }
função parseJSON(str) { /* ... */ }
função apiRequest(url) { /* ... */ }
função debounce(fn, delay) { /* ... */ }
função acelerador(fn, limit) { /* ... */ }
// ... Mais de 100 funções não relacionadas

Porque é que é errado: Um enorme ficheiro contém utilitários de validação, formatação, análise, chamadas API e desempenho. Encontrar debounce() requer a deslocação através de centenas de funções não relacionadas. Várias equipas que modificam este ficheiro criam conflitos de fusão constantes.

Conformidade:

// validação/email.js
exportar função validateEmail(email) { /* ... */ }

// validação/telemóvel.js
exportar função validatePhone(phone) { /* ... */ }

// formatação/moeda.js
exportar função formatCurrency(montante) { /* ... */ }

// formatação/data.js
exportar função formatDate(date) { /* ... */ }

// api/request.js
exportar função apiRequest(url) { /* ... */ }

// performance/debounce.js
exportar função debounce(fn, delay) { /* ... */ }

Porque é que isto é importante: Cada função de utilitário num ficheiro dedicado dentro de diretórios categorizados. Encontrar debounce() significa navegar para desempenho/debounce.js diretamente. As equipas que trabalham em diferentes utilitários não entram em conflito porque estão em ficheiros separados.

Conclusão

Sempre que possível, mantenha os ficheiros com menos de 500 linhas. Quando os ficheiros excederem este limite, procure responsabilidades distintas que possam ser extraídas para módulos separados. Organize os ficheiros relacionados em diretórios para manter a estrutura e, ao mesmo tempo, manter os ficheiros individuais concentrados e fáceis de manter.