Skip to content

proof-spec.md

Latest commit

 

History

History
114 lines (83 loc) · 2.79 KB

proof-spec.md

File metadata and controls

114 lines (83 loc) · 2.79 KB

Proof Files Specification

Overview

The proof/ directory contains one .java file per pattern slug. Each file wraps the pattern's modern code in a compilable program, proving that every code snippet shown on the site actually compiles with the advertised JDK version.

Only the modern code is proven — the old code is what we're moving away from.

Directory Layout

proof/
  language/
    TypeInferenceWithVar.java
    RecordsForDataClasses.java
    SealedClasses.java
    ...
  collections/
    ImmutableListCreation.java
    ...
  strings/
  streams/
  concurrency/
  io/
  errors/
  datetime/
  security/
  tooling/
  enterprise/

The folder structure mirrors content/ — one subfolder per category.

File Conventions

Naming

  • Folder: matches the category name (e.g., language/, collections/)
  • File: PascalCase version of the slug (e.g., type-inference-with-var → TypeInferenceWithVar.java)

Structure

Each proof file follows this structure:

import java.util.*;  // whatever imports the snippet needs

/// Proof: {slug}
/// Source: content/{category}/{slug}.yaml
void main() {
    // modern code from the pattern, adapted to compile
}

Key rules:

  1. Use implicit class and void main() — Java 25 supports running single-file programs without an explicit class declaration
  2. Add necessary imports — the snippet JSON/YAML doesn't include imports; add whatever is needed for compilation
  3. Add minimal scaffolding — if the snippet references variables or types not defined in the code, add stub declarations so it compiles
  4. Keep it minimal — the goal is compilation proof, not a full test suite
  5. Include the /// Proof: and /// Source: comments — links the proof file back to the content source

What to avoid

  • Don't add runtime assertions or test logic
  • Don't restructure the modern code — keep it as close to the snippet as possible
  • Don't add the old code

Running Proof Files

Compile a single file

java --enable-preview proof/language/TypeInferenceWithVar.java

Compile all proof files

# Compile every proof file and report failures
find proof -name '*.java' -exec sh -c '
  echo "Compiling: $1"
  java --enable-preview "$1" 2>&1 || echo "FAILED: $1"
' _ {} \;

Prerequisites

  • Java 25+ — proof files use implicit classes and void main() which require --enable-preview

Adding a Proof File

When adding a new pattern:

  1. Create the content file under content/category/slug.yaml
  2. Create a proof file under proof/category/SlugName.java
  3. Copy the modernCode from the pattern into the void main() body
  4. Add imports and minimal scaffolding to make it compile
  5. Run java --enable-preview proof/category/SlugName.java to verify