User:Duesentrieb/Architecture Guidelines

This is a DRAFT of a PROPOSAL for a RECOMMENDATION regarding code architecture. It is written with MediaWiki core in mind, but should be applicable to any software project of similar size and intent, regardless of language or platform.

With regards to MediaWiki, it's important to realize that a lot of the core code is quite old, or was built upon antique foundations, and does not conform to the principles described in this document. It should also be clear that any general principle should not be taken as a fixed rule, and that applying such principles in an environment that does not adhere to them is difficult.

The general principles laid out below should serve as a guideline when writing and reviewing new code, and when refactoring old code.

Testability

 * Injection & Mocking
 * CI & confidence
 * Coverage
 * Unit vs Integration

Values

 * Typically "newable"
 * Equals, toString, hashing, etc
 * Immutable, unless there is a very good reason
 * If Mutable: LSP, cloning
 * Often no interface, single impl
 * If multiple implementations, use a factory
 * Mutable value -> Model, mutable list/map, etc

Builders and Cursors

 * Represent state
 * Cursors typically for I/O
 * Builders typically for complex values
 * Model == Builder?

Services

 * Typically application scope
 * "Stateless" singletons (state: lazy initialization, caching)
 * Storage, formatting, etc

Factories

 * newXXX has parameters (or the whole purpose is lazy init)
 * inject context knowledge
 * Constructs values or controllers, rarely services

Registries

 * Lazy init of services / factories / registries
 * newXXX has no parameters
 * DI entry point
 * Should not be passed around
 * App: defines application as service network
 * App: may have static singleton

Controllers

 * Business case
 * Use services
 * Created by factory
 * May be stateful

Method Level

 * Contract vs Implementation

Medium Level

 * logical data model
 * information flow
 * hooks, options, etc

Guides and Howtos

 * Install & Update
 * Backup/Restore
 * Extending