C-DAD vs. Code Comments

A comment is the cheapest way to leave a note for the next person, and plenty of comments earn their keep. The problem was never that comments are worthless. It's that a comment lives inside the exact code it describes, and code changes for reasons that have nothing to do with keeping the comment true.

Take an anti-pattern that shows up constantly in early drafts of a contract, before anyone's cleaned it up: a description that says something like "retries using exponential backoff until the gateway responds." That sentence describes an implementation detail, not a guarantee. Six months later someone swaps the backoff strategy for something smarter, the comment stays exactly where it was, and now it's actively wrong instead of merely stale. A better version, "retries only after the upstream system has confirmed the original request is safe to repeat," survives that refactor because it describes the behavior that has to stay true, not the mechanism that happens to implement it today.

That's the structural problem with comments as a source of truth. Nothing forces them to change when the code around them does, and nothing flags it when they don't. A contract is deliberately built as a separate, versioned artifact instead of being embedded in the function it describes, and cdad validate checks it against versioning rules and generated-artifact consistency before it can drift too far from reality. It's a small difference in location with a large difference in outcome.

Comments still matter for the small, local "why did I write it this way" notes that don't rise to the level of a capability's behavior. A contract isn't trying to compete there. What it's built for is the higher-stakes question a comment was never designed to answer reliably: can someone who's never touched this code make a safe change to it, months or years after the person who wrote the comment has moved on.