Some Thoughts About Software Architecture

Object-Oriented Semantics

Object Classes

• Object Classes are classes.
• They define some set of public methods.
• They define some set of private fields.

Message Classes

• Message Classes are Object Classes.
• They don't allow mutation.
• They don't define methods that have impure preconditions.
• They don't define methods that have impure postconditions.

Value Classes

• Value Classes are Message Classes.
• They enforce some set of value constraints.
• Inheritance is used mostly to enforce additional value constraints.

Record Classes

• Record Classes are Message Classes.
• They expose some set of properties.
• Inheritance is used mostly to expose additional properties.

Ports

• Ports are interfaces.
• They declare methods that have impure preconditions.
• They declare methods that have impure postconditions.

Axiomatic Ports

• Axiomatic Ports are Ports.
• They specify functionality to be imported or injected.

Derived Ports

• Derived Ports are Ports.
• They specify functionality to be exported or extracted.

Adapters

• Adapters are Object Classes.
• They define methods that have impure preconditions.
• They define methods that have impure postconditions.

Axiomatic Adapters

• Axiomatic Adapters are Adapters.
• They implement functionality to be imported or injected.

Derived Adapters

• Derived Adapters are Adapters.
• They implement functionality to be exported or extracted.

Comments

The terminology here is based on the terminology from Hexagonal Architecture (also called Ports and Adapters), but "derived" and "axiomatic" are being used instead of "primary" and "secondary" to emphasize the nature of the distinction.

The properties of a record should be orthogonal to each other, meaning that you can't infer anything about the value of one property based on the value of another. Otherwise there's a risk of inconsistency, and you need to go out of your way to validate the relevant invariants.

Adapters exist mostly to define input/output methods, and input/output methods should generally be asynchronous. This might be implemented with async/await in high-level languages. But in low-level languages, adapters are implemented with explicit state machines and message loops.

Aside from the current state of the state machine, and perhaps an immutable configuration, it's reasonable for adapters to be stateless. If there is a configuration, then it influences the set of interfaces that the adapter can reasonably implement. A configuration that exposes more properties, or more constrained values, can be used to implement more interfaces.

Adapters often expose methods that can change the state of a database. As a rule, those methods should be (a) idempotent and (b) transactional.

A distinction can be made between adapters that interact directly with the external world and those that don't. Adapters that interact directly with the external world must be written in a different language, because the runtime for a language cannot be implemented using the language itself.

Different adapters can exist at different layers of abstraction. Higher layers of abstraction should completely hide lower layers of abstraction, and they should reduce the exposed surface area in the process. This makes it easier to replace a given layer.

Messages are self-contained blobs of immutable state, and adapters are machines that change the world by pushing messages through pipes. A program that can't be understood in those terms, e.g. because messages sometimes push adapters through pipes, is very hard to reason about.

This isn't meant to be an exhaustive taxonomy of things-that-have-reasonable-semantics, but it is meant to be a step in that general direction.

Project Organization

Public Specification

• The public specification includes Message Classes and Ports.
• It does not include Adapters.
• It does not depend on the internal specification, the internal implementation, or the public implementation.
• Every type that it defines has public visibility.

Internal Specification

• The internal specification includes Message Classes and Ports.
• It does not include Adapters.
• It does not depend on the internal implementation or the public implementation.
• Every type that it defines has internal visibility.

Internal Implementation

• The internal implementation includes Adapters.
• It does not include Message Classes or Ports.
• It does not depend on the public implementation.
• Every type that it defines has internal visibility.

Public Implementation

• The public implementation includes Adapters.
• It does not include Message Classes or Ports.
• Every type that it defines has public visibility.

Semantic Versioning

• A major version change seems to indicate a change in the public specification of a software component, such that subtyping rules don't allow compatibility.
• A minor version change seems to indicate a change in the public specification of a software component, such that subtyping rules do allow compatibility.
• A patch version change seems to indicate a change in the implementation of a software component.
• The subtyping rules aren't obvious. (Are specifications covariant with respect to some types, contravariant with respect to other types, and invariant in all other cases?)
• Package managers should validate/enforce semantic versions, but they (mostly?) don't.
• It's not clear to me that semantic versions will actually be used when we eventually solve the problems that package managers have (mostly?) failed to solve.