Deciding where a newly created file belongs—between ambiguous directories like utils, helpers, libs, and core—is a perennial dilemma across software teams. When boundaries are vague, developers invent arbitrary subdirectories, resulting in tangled imports and code duplication.
Examining major open source projects reveals clear, pragmatic principles for structuring codebases cleanly.
1. There Is No Universal Template
Different architectures demand different organization styles:
- Vue.js: Houses cross-cutting helpers under a
shared/folder alongside dedicated component packages. - Axios: Separates code into
core/(domain-specific HTTP dispatching) andhelpers/(generic functions). - Django: Groups by functional responsibility (
middleware,forms,db,conf). - FastAPI: Keeps top-level modules relatively flat within the primary namespace before nesting.
Because no single folder structure fits every system, the key requirement is establishing and documenting clear, explicit boundaries.
2. The Axios Test: Domain-Specific vs. Generic
Axios provides one of the cleanest mental models in open source by articulating the purpose of each directory in its documentation:
core/: Contains modules strictly coupled to the application's domain logic (HTTP lifecycle, interceptors, dispatch pipelines).helpers/: Contains pure, generic utility functions with zero domain knowledge. As the Axios README notes: These modules could theoretically be published to npm on their own and consumed by other unrelated apps.
If a string sanitizer or date formatting helper could be dropped into another company's project without modification, it is a generic helper/utility. If a function validates user session tokens or formats domain order schemas, it belongs in your domain/core layer.
3. Favor Shallow Hierarchies First
Premature directory nesting is a frequent anti-pattern in growing projects. Creating nested trees (src/services/billing/providers/stripe/validators/card.py) for a three-file project yields several problems:
- Navigation friction increases dramatically.
- Refactoring becomes cumbersome because directory boundaries were committed to before the domain solidified.
The Organic Growth Rule
- Start with flat files: Write
utils.pyorcrawler.pybefore creating a directory. - Split only upon pain: When
crawler.pyexceeds several hundred lines with distinct responsibilities, promote it to a package:crawlers/ ├── __init__.py ├── base.py ├── securities.py └── exchange.py - Keep directory depth under 3 levels whenever possible. Shallow hierarchies make relationships transparent at a glance.
Summary Checklist
utils//helpers/: Completely decoupled from business models; pure inputs and outputs.- Domain modules: Named after business capabilities (
billing/,auth/,orders/). core/: Infrastructure wiring that binds the domain together (application factory, global config, database lifecycle).- Default to shallow: Let files grow before introducing new folder abstractions.