Design by Contract-style Coding Comments for Humans and AI

Read the complete 5-part article at WhatsOnYourBrain.com

We've all been there. You open a file you wrote six months ago, and it might as well have been written by a stranger. Or worse - you inherit a codebase with comments like:

// Fix for bug
const x = calculateThing(y);

Thanks for nothing, past developer.

The Problem With Traditional Comments

Most code comments fall into two categories:

Obvious comments that restate what the code does:
```
// Increment counter
counter++;
```
Vague comments that don't explain why or what constraints exist:
```
// TODO: Fix this later
// Don't change this
```

Neither helps when you're trying to understand a system's invariants, constraints, or the reasoning behind architectural decisions.

Enter: CONTRACT-Style Comments

I developed this approach while working on my guitar training web app. I have a history of brain trauma, which means I sometimes forget context when I return to projects. I needed comments that would bring me (or anyone else) up to speed instantly.

Here's what a CONTRACT comment looks like:

//
//  THIS FILE DEFINES THE CORE ENGINE.
//
//  The ENTIRE application depends on the following invariants:
//
//  1. DEGREE IS THE ONLY SELECTOR.
//     • Degree determines which rotation of the mode template is used.
//     • Degree MUST be an integer 1–7.
//     • DO NOT add new selectors.
//
//  2. TONIC IS CONTEXT, NOT STRUCTURE.
//     • Tonic determines absolute semitone + note names.
//     • Tonic MUST be passed in from #tonic.
//     • DO NOT remove tonic from function signatures.
//
//  3. OUTPUT SHAPE IS FIXED.
//     Each note object MUST contain EXACTLY these keys:
//
//         {
//             degree: <1–7>,
//             relSemitones: <0–11>,
//             semitones: <0–11>,
//             note: <string>
//         }
//
//     DO NOT rename these keys.
//     DO NOT add new keys.
//     DO NOT remove keys.
//
//  BREAKING ANY OF THESE RULES WILL BREAK THE ENTIRE APP.
//
// ─────────────────────────────────────────────────────────────

Notice what this does differently:

Establishes invariants (what MUST stay true)
Explains consequences (what breaks if you violate rules)
Uses visual hierarchy (all-caps keywords, bullets, separators)
Defines contracts (expected inputs/outputs)
States prohibitions explicitly (DO NOT do X)

Why This Matters for AI Coding Assistants

I work with Claude Sonnet in the Zed text editor as my AI coding assistant. When Claude opens a file cold, CONTRACT comments make an enormous difference.

Here's why, in Claude's own words:

For example, I am Claude Sonnet, and when I encounter CONTRACT-style comments, I can immediately understand:

What invariants I must preserve when making changes

What constraints exist and why they're there

What will break if I modify certain parts of the system

Without these comments, I might suggest changes that technically work but violate architectural assumptions. With CONTRACT comments, I can make intelligent suggestions that respect your system's design. Even when dealing with legacy code or technical debt, I know what's intentional versus what's a known issue.

This isn't just theoretical. When Claude helped me fix Open Graph tags in my WinterCMS site header, the CONTRACT comments we added meant that the next time we touch that file - whether it's me in six months or Claude in a fresh conversation - the context is already there.

The CONTRACT Template

Here's a practical template I use:

<!--
═══════════════════════════════════════════════════════════
                    [FILE/SECTION NAME]
                    [Brief Purpose Statement]
═══════════════════════════════════════════════════════════

PROJECT CONTEXT:
────────────────
[1-2 sentences about what this file is part of]

CRITICAL INVARIANTS - DO NOT BREAK THESE:
──────────────────────────────────────────

1. [RULE NAME]
   • What this means
   • MUST/MUST NOT constraint
   • Why it matters
   • What breaks if violated

2. [RULE NAME]
   • ...

KNOWN ISSUES & TECHNICAL DEBT:
───────────────────────────────
• [Issue 1 - why it exists, when to fix]
• [Issue 2 - constraints preventing fix]

FUTURE IMPROVEMENTS:
────────────────────
• [Improvement 1]
• [Improvement 2]

═══════════════════════════════════════════════════════════
-->

Practical Guidelines

DO:

State what MUST or MUST NOT happen
Explain why constraints exist
Document what breaks if rules are violated
Use visual hierarchy (caps, bullets, separators)
Include "known issues" sections for technical debt
Add "future improvements" for roadmap clarity

DON'T:

Just describe what the code does (code already does that)
Write vague warnings like "be careful here"
Skip the why behind decisions
Assume future you will remember context

Real-World Example

Here's a snippet from my website's header file:

<!-- ═══════════════════════════════════════════════════════
     OPEN GRAPH PROTOCOL META TAGS
     ═══════════════════════════════════════════════════════
     
     CRITICAL INVARIANT:
     ───────────────────
     OG IMAGE DIMENSIONS MUST MATCH ACTUAL FILE.
     
     • File: /themes/radiantweb-guitar/assets/images/[email protected]
     • Actual dimensions: 753 × 258 pixels
     • Format: PNG with RGBA
     • DO NOT change dimensions unless you change the file
     • Social platforms WILL reject if dimensions mismatch
     
     TESTING YOUR OG TAGS:
     ─────────────────────
     • Facebook: https://developers.facebook.com/tools/debug/
     • LinkedIn: https://www.linkedin.com/post-inspector/
     • Twitter: https://cards-dev.twitter.com/validator
     ═══════════════════════════════════════════════════════ -->
<meta property="og:image:width" content="753">
<meta property="og:image:height" content="258">

This comment:

States the invariant clearly
Explains the consequence of breaking it
Provides actionable testing steps
Uses visual separators for scannability

Who Benefits?

You, six months from now when you've forgotten why you made certain decisions.

New team members who need to understand the system quickly.

AI coding assistants like Claude, GitHub Copilot, or Cursor that need to understand constraints before suggesting changes.

Junior developers learning why rules exist, not just what they are.

Open-source contributors who want to help but need context.

The Bottom Line

Everyone forgets. Everyone context-switches. Everyone benefits from clear contracts.

CONTRACT-style comments aren't about writing more documentation - they're about writing better documentation that establishes boundaries, explains constraints, and documents consequences.

In an era where AI assistants are becoming standard development tools, investing in LLM-friendly comments pays dividends. But more importantly, it pays dividends for you - the human who has to maintain this code.

Your future self will thank you.

About the Author

Jeffrey Sabarese (ajaxStardust) is a guitar instructor and web developer in State College, PA. He builds educational tools like the guitar theory trainer at finga.studio. He works with Claude Sonnet in Zed as his AI coding assistant and advocates for documentation practices that help both humans and AI understand code better.

Find him at:

Website: finga.studio
Guitar Trainer: finga.studio
Community Forum: talk.finga.studio

Related Work: CONTRACT‑Style‑Comments (CSC)

The ideas explored in this article connect directly to my formalized framework CONTRACT‑Style‑Comments, now published as an open GitHub repository:

Access it the Contract-Style Comments repo on GitHub:

CSC provides a structured, three‑artifact governance model designed for both human developers and stateless AI agents. It addresses the same core problem discussed here:
how to prevent architectural drift and comprehension debt in systems touched by AI.

Why CSC Matters in This Context

It externalizes invariants into CONTRACT.md
It externalizes reasoning into WHY.md
It externalizes operational truth into QUICKSTART.md
It gives AI agents a safe, bounded interface
It reduces the cognitive load that fuels comprehension debt