Rule

Avoid overly large files.
Large files with multiple responsibilities
are hard to maintain.

Supported languages: 45+

Introduction

Files spanning thousands of lines typically handle multiple unrelated concerns, making it difficult to locate specific functionality. A 3000-line utils.js file containing validation helpers, string formatting, date manipulation, and API utilities forces developers to scroll through unrelated code to find what they need. Large files also create merge conflicts as multiple developers modify different sections simultaneously.

Why it matters

Code maintainability: Large files mix unrelated functionality, requiring developers to understand hundreds of lines of irrelevant code to modify one function. Finding specific logic becomes a search exercise rather than navigating to an appropriately named file.

Version control conflicts: When multiple developers work on different features in the same large file, merge conflicts occur frequently. Smaller, focused files enable parallel development as each developer works in separate files.

Code review efficiency: Reviewing changes in large files requires more context. Reviewers must understand how modifications affect other unrelated code in the same file. Smaller files make the scope of changes obvious, speeding up reviews.

Code examples

❌ Non-compliant:

// utils.js (1500+ lines)
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) { /* ... */ }
// ... 100+ more unrelated functions

Why it's wrong: One massive file contains validation, formatting, parsing, API calls, and performance utilities. Finding debounce() requires scrolling through hundreds of unrelated functions. Multiple teams modifying this file create constant merge conflicts.

✅ Compliant:

// 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) { /* ... */ }

Why this matters: Each utility function in a dedicated file within categorized directories. Finding debounce() means navigating to performance/debounce.js directly. Teams working on different utilities don't conflict because they're in separate files.

Conclusion

Keep files under 500 lines when possible. When files exceed this, look for distinct responsibilities that can be extracted into separate modules. Organize related files in directories to maintain structure while keeping individual files focused and maintainable.