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

Maintainability

 * what vs why
 * operation vs intent

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, views, etc
 * converters (formatters, serializers, 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
 * MVC

Glue

 * adapters
 * decorators
 * event/hook handers
 * callbacks

Security

 * Interface contracts (escaped vs unescaped)

Information Locality

 * need to know
 * keep it local
 * information hiding

Composition
Composition vs. Inheritance Protected vs. Private

Class Level

 * Concept
 * Purpose
 * Relationship with other classes/interfaces
 * Usage

Method Level

 * Contract vs Implementation
 * array structures
 * formats / escaping

Medium Level

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

Guides and Howtos

 * Install & Update
 * Backup/Restore
 * Extending