The Sculpture Principle

“Remove until removal would break meaning” - Like Michelangelo seeing David in the marble, see the essential algorithm within the verbose code.

Core Philosophy

Great code, like great sculpture, emerges not from addition but from removal. Every line must earn its place. When nothing more can be removed without losing essential meaning, you have found the true form.

Guiding Questions

1. “What is the invariant?”

Identify the core truth your code must express. Everything else is scaffolding waiting to be removed.

Example: A test validating that @return Standard<T> requires @phpstan-self-out self<T>. That’s the invariant - everything else supports this single truth.

2. “Can this be a transformation?”

Complex logic often hides simple transformations. Look for the direct path.

Example: Instead of parsing and comparing type parameters:

// Before: Complex parsing and validation
if (preg_match('/Standard<(.+?)>/', $returnType, $matches)) {
    $returnGeneric = $matches[1];
    // ... more parsing ...
}

// After: Direct transformation
$expectedSelfOutType = str_replace('Standard', 'self', $returnType);

3. “Does this branch add meaning?”

Every conditional must justify its existence. Each branch should handle a meaningfully different case.

Example: Multiple skip conditions collapsed to one: “not a Standard type.” The other conditions were just avoiding the real test.

4. “What would a mathematician write?”

Mathematical proofs are terse yet complete. Strive for the same clarity.

Example:

• Given: A method returns Standard<T>
• Then: It must have self<T> annotation
• Proof: assertSame(expected, actual)

5. “Can the data flow?”

Let data flow naturally through your pipeline. Avoid unnecessary collection and transformation.

Example:

// Before: Collecting unnecessarily
return take($methods)->filter()->map()->toList();

// After: Natural flow
return take($methods)->filter()->map();

6. “Name the essence”

Method names should capture exactly what they do - no more, no less.

Example: firstMatch() - finds the first regex match. The name is the specification.

The Refactoring Journey

1. Identify verbose code - Complex, multi-purpose methods
2. Separate concerns - Each component does one thing
3. Find the pattern - What is the code really doing?
4. Remove conditions - Which branches are essential?
5. Simplify data flow - How can data move most naturally?
6. Name with precision - What would you call this if you could only use three words?

Practical Application

When approaching code, ask:

• “What is the one thing this must prove?”
• “Can I express this as a transformation?”
• “What would remain if I could only keep one line?”
• “Does each line earn its place?”
• “Can the types flow through naturally?”

The Test Case Study

Our TypeConsistencyTest transformation:

Before

• 80+ lines
• Multiple conditionals
• Complex parsing logic
• Mixed concerns

After

• 40 lines
• One skip condition
• One transformation
• Single responsibility

The entire validation logic became:

$expectedSelfOutType = str_replace('Standard', 'self', $returnType);
$this->assertSame($expectedSelfOutType, $selfOutType, "...");

The Breathing Principle

“My goal is to make art as easy as breathing” - Vincent van Gogh

Where the Sculpture Principle focuses on removal until only essence remains, the Breathing Principle focuses on the experience of reading that essential code. Code should flow as naturally as breath - no cognitive pauses, no mental strain, just effortless understanding.

The Two Principles Work Together

Consider how they complement each other:

// This makes you hold your breath - cognitive load at every line
if (preg_match('/Standard<(.+?)>/', $returnType, $returnMatches)) {
    $returnGeneric = trim($returnMatches[1]);
    $this->assertNotNull($selfOutType, "...");
    if (!preg_match('/self<(.+?)>/', $selfOutType, $selfOutMatches)) {
        $this->fail("...");
        return;
    }
    // ... more parsing ...
}

// This flows like breathing - natural, effortless
$expectedSelfOutType = str_replace('Standard', 'self', $returnType);
$this->assertSame($expectedSelfOutType, $selfOutType, "...");

The second version doesn’t make you pause to parse regex, track variables, or navigate conditionals. You read it, you understand it, you move on. Like breathing.

Natural Flow in Practice

This principle guides Pipeline’s design itself:

// Natural as breathing
take($users)
    ->filter(fn($u) => $u->isActive())
    ->map(fn($u) => $u->email)
    ->each(fn($email) => send($email));

Each line flows into the next. No cognitive speed bumps. No need to hold state in your head. Just follow the data as it flows through transformations.

The Synthesis

• Sculpture: Remove until only truth remains
• Breathing: Arrange that truth so it flows naturally

Code that achieves both is truly sublime - minimal yet fluid, essential yet effortless.

Remember

The goal is code so clear that it feels inevitable, as if it could not have been written any other way. When you achieve this, you have found the sculpture within the stone - and arranged it so beautifully that reading it is as natural as breathing.

By @sanmai