Uniword uses Ruby’s autoload mechanism for lazy loading of most classes, achieving 90% autoload coverage for improved startup performance and maintainability.
1. Autoload Coverage
The codebase has two categories of file loading:
-
95 autoload statements — Classes loaded on-demand when first accessed
-
10 require_relative statements — Well-documented exceptions for architectural necessities
Most classes are never loaded until they are actually needed. This means that opening a simple document does not load the math, chart, or presentation modules.
2. Architectural Exceptions
The following 10 files MUST use require_relative (not autoload):
- Base Requirements (2)
-
-
uniword/version— Version constants needed by gem metadata -
uniword/ooxml/namespaces— Namespace constants referenced by generated classes
-
- Namespace Modules (6)
-
-
Core namespaces (wordprocessingml, wp_drawing, drawingml, vml, math, shared_types)
-
Required due to deep cross-dependencies with format handlers
-
Constant assignments require immediate class resolution
-
- Format Handlers (2)
-
-
formats/docx_handlerandformats/mhtml_handler -
Self-registration side effects require eager loading
-
|
These exceptions are architectural necessities, not technical debt. Attempting to autoload these modules would cause |
3. Performance Benefits
- Faster startup
-
Only essential classes are loaded initially. Document creation begins without loading 760 element classes.
- Lower memory footprint
-
Unused features do not consume memory. If you never use math equations, those classes stay unloaded.
- Better maintainability
-
Clear separation between eager and lazy loading makes the codebase easier to understand and modify.
4. Adding New Classes
When adding new classes, default to autoload:
# In lib/uniword.rb
autoload :DocumentValidator, 'uniword/document_validator'Only use require_relative if the class has load-time side effects, is referenced in module-level constants, or has deep cross-dependencies with eagerly loaded modules.