Contract-Based Design and Communication Challenges in Software Development

In daily development work, engineers often spend a lot of time on ineffective cross‑team communication: outdated documents, undocumented changes, unclear error codes, and endless alignment meetings. These problems consume significant effort and lead to fragile systems.

The article first outlines typical pain points:

Fake documentation: Lack of a standard protocol leads to ad‑hoc agreements (JSON, protobuf, wiki, even a single sentence) that can be silently changed, increasing risk.

Undocumented changes: When upstream or downstream services modify fields or add required parameters without proper notification, failures occur.

Unclear error codes: Downstream error codes are either wrapped in custom formats or passed through directly, making troubleshooting a detective job.

It argues that merely following good habits (interface‑first, timely docs, compatibility‑first updates, clear error‑code contracts) is insufficient because human error is inevitable. A systematic solution is needed.

The second part encourages thinking like a product manager: observe real‑world scenarios, define the core problem (information loss in team communication), and derive insights from Conway’s Law that organizational structure mirrors system architecture.

Next, the article introduces contract‑based design (Design by Contract). It explains the origin of the concept, its three core elements—preconditions, postconditions, and invariants—and how they can be applied to API contracts to make responsibilities explicit.

Example code demonstrates a square‑root function with contract annotations:

/**
 * @brief 计算非负数的平方根
 * @param number 要计算平方根的非负数
 * @return double 输入数的平方根
 * @Precondition 输入数必须是非负的 (number >= 0)
 * @Postcondition 返回值必须是非负的，并且其平方应等于输入数
 * @Invariant 输入数在函数执行过程中保持不变
 * @throws std::invalid_argument 如果输入数为负
 * @throws std::logic_error 如果计算结果不符合预期
 */
double calculateSquareRoot(double number) {
    // 前置条件: 输入数必须是非负的
    if (number < 0) {
        throw std::invalid_argument("输入数必须是非负的");
    }
    // 不变式: 输入数在计算过程中保持不变
    double result = std::sqrt(number);
    // 后置条件: 结果必须是非负的，并且其平方应等于输入数
    if (result < 0 || std::abs(result * result - number) > 1e-9) {
        throw std::logic_error("计算结果不符合预期");
    }
    return result;
}

Another snippet shows a typical error‑code JSON returned by a downstream service:

{
    "code": 71756425,
    "message": "系统繁忙"
}

And a protobuf contract example illustrates how a seemingly simple interface definition often lacks essential context such as usage scenarios, constraints, and error handling:

message GetUserBalanceReq {
    string user_id = 1;
    string user_type = 2;
}
message GetUserBalanceRsp {
    int32 code = 1;
    string message = 2;
    int32 balance = 3;
}
service testsvr {
    rpc GetUserBalance(GetUserBalanceReq) returns (GetUserBalanceRsp) {};
}

The article then discusses defensive programming in the AI era, suggesting that large‑model tools (e.g., Copilot, Cursor) can automate repetitive contract‑related tasks, allowing developers to focus on reviewing code rather than writing boilerplate.

Finally, it expands the notion of contracts beyond individual APIs to the whole development lifecycle—business modeling, analysis, and design—emphasizing that a well‑structured contract at each stage helps align teams, reduce entropy, and improve reliability.

The piece concludes with a call to reflect on real communication problems, adopt contract‑based methodologies, and leverage AI assistance to build more robust software systems.