Cleanliness

⚠️ LLM-generated content notice: Parts of this page may have been created or edited with the assistance of a large language model (LLM). The prompts that have been used might be on the page itself, the discussion page or in straight forward cases the prompt was just "Write a mediawiki page on X" with X being the page name. While the content has been reviewed it might still not be accurate or error-free.

Cleanliness in Software Engineering

Definition

Cleanliness is defined as:

Cleanliness = (Number of Valid Possible States) / (Total Possible States)

Higher cleanliness implies that the system design prevents invalid states by construction.

Examples

✅ Good Cleanliness (High Valid/Total Ratio)

Type-safe Enums

enum OrderStatus { NEW, PROCESSING, SHIPPED, DELIVERED }

• Valid states = 4, Total states = 4 ⇒ Cleanliness = 1.0

Finite State Machines

Workflow like: Draft → Submitted → Approved/Rejected.

• Explicit transitions only, impossible to enter an invalid state without a logic error.

Null Object Pattern

Logger logger = new NullLogger(); // instead of null

• Eliminates null as a possible invalid state.

Constructor Validation

public User(String email) {
  if (!email.contains("@")) throw new IllegalArgumentException();
}

• Ensures object is only created in a valid state.

❌ Bad Cleanliness (Low Valid/Total Ratio)

Public Mutable Fields

public class Account {
  public double balance;
}

• balance can be negative, NaN, etc. ⇒ low cleanliness.

Using Ints for Enums

int status = 3; // 0 = new, 1 = processing, 2 = shipped

• Valid = 3, Total = 2^32 ⇒ Cleanliness ≪ 1

Comment-only Constraints

def update_profile(data):  # "email must be present"
    ...

• Nothing enforces constraints at runtime ⇒ unclean

Boolean Flag Explosion

processFile(file, true, false, true);

• 3 booleans ⇒ 2^3 = 8 combinations, only 2–3 valid.

Summary Table

Example	Valid States	Total States	Cleanliness	Comment
Enum types	4	4	1.0	Clean
FSM	~5	~5	1.0	Clean
Null Object	1	2	0.5 → 1.0	Clean after pattern
Constructor checks	n	n	1.0	Clean
Mutable fields	~100	∞	≪ 1	Dirty
Int as enum	3	2^32	≪ 1	Dirty
Doc-only constraints	low	high	≪ 1	Dirty
Boolean flags	3	8	0.375	Dirty

Argument Against Traditional Mathematical Proofs

Problem Statement

Traditional proof-based approaches assume:

• Infinite state spaces (ℕ, unbounded recursion)
• Perfect memory and time
• Symbolic models divorced from execution limits

In engineering terms:

• RAM, CPU, and wall time are limited
• Many mathematically valid states are practically invalid

Consequence: Near-zero Cleanliness

Proof-based systems do not eliminate invalid runtime states:

• Stack overflows
• Out of memory errors
• Timeouts or hangs

System	Total States	Valid States (in practice)	Cleanliness
Unbounded int stack	∞	bounded depth	≈ 0
Turing machine	∞	RAM-limited steps	≈ 0
Isabelle/HOL proofs	Symbolic	Execution-bounded	≈ 0

Misalignment Summary

The closer a system aligns its representational power to its runtime constraints, the cleaner it is. Proof-based systems optimize for expressiveness, inherently bloating the total possible state space and reducing cleanliness — by design.

Conclusion

• Cleanliness is a practical, quantifiable lens for software design quality.
• Overly symbolic or theoretically pure systems often fail in real-world constraints.
• Clean engineering involves bounding state spaces, using types, and designing for reality — not mathematical infinity.