Comparisons

Overview

Most teams that look at C-DAD are not starting from zero. They already write documentation, leave comments in the code, maintain an OpenAPI spec, keep a folder of architecture decision records, or are eyeing a rewrite as the fix for a system nobody trusts anymore. The question is never whether a contract is better than nothing. It's whether a contract does something those existing artifacts don't.

This section works through five comparisons on their own terms. None of them exist to declare a winner. Documentation, comments, OpenAPI, and ADRs all solve real problems, and a contract doesn't replace any of them wholesale. What follows is where each one falls short for the specific job a contract is built to do: giving an agent, or a new engineer, enough to act safely without tracking down someone who remembers why.

Pages in this area

• C-DAD vs. Documentation

  Documentation is prose for humans to interpret. A contract is structured enough for an agent to act on directly.

• C-DAD vs. Code Comments

  Comments live inline and drift with the code around them. A contract is a separate artifact that gets checked, not just read.

• C-DAD vs. OpenAPI

  OpenAPI describes the shape of a request. A contract describes why the rule inside it exists.

• C-DAD vs. Architecture Decision Records

  An ADR records a decision at the moment it was made. A contract stays validated against the system as it runs today.

• C-DAD vs. A Full Rewrite

  A rewrite spends months producing cleaner code that still can't explain itself. Extraction fixes legibility one capability at a time.