Why Simplicity Wins: Turning Complex Code and Design into Clean Solutions

Background

Last week a new requirement revealed a historic feature that turned a simple task into a tangled mess, reinforcing the core idea that simplifying complexity is an eternal challenge in product design and software development. As described in The Mythical Man‑Month , complexity can be divided into essential complexity (inherent to the problem) and accidental complexity (caused by poor choices or methods).

Why Simplicity?

Simplicity is not about being less capable; it is about making logic intuitive, reducing learning curves, and enabling new developers to understand and modify code quickly.

Case Details

1) Product Design

The business involves several Promise types (fresh, air, ordinary parcels) that map one‑to‑one with document and job types. Because the mapping is 1:1, the intermediate document type is redundant and can be removed, simplifying both the data model and the code.

Similarly, job types are essentially the same as business types; unifying terminology eliminates confusion and eases communication.

2) Code Issues

Long internal call chain :

getBusinessTypeInfoForAll → getBusinessTypeInfo → getOrderCategoryNew → obtainOrderCategoryByCode → filterBusinessType

This widespread usage makes the code hard to manage and reveals a lack of clear layered architecture.

Side effects in filterBusinessType:

public int filterBusinessType(Request request, Response response) {
    // ...
    // Returns an int but also modifies response
}

The method violates the Single Responsibility Principle and the Principle of Least Surprise because callers cannot predict the modification of response.

Incorrect implementation (return before side‑effect):

public int filterBusinessType(Request request, Response response) {
    if (...) {
        return ...; // side‑effect may be skipped
    }
    boolean flag = isXXX(request, response);
}

Correct implementation (perform side‑effect first, then return):

public int filterBusinessType(Request request, Response response) {
    /**
     * Ensure return occurs after isXXX, because external code reads response.A()
     */
    boolean flag = isXXX(request, response);
    if (...) {
        return ...;
    }
}

Suggested strategies:

Separate concerns: one method returns the business type, another sets the response.

Return a composite object containing both the result and the response.

public int filterBusinessType(String logPrefix, Request request) {
    // filtering logic
    int businessType = ...;
    return businessType;
}

public void setResponseData(int filterResult, Response response) {
    response.setFilteredData(...);
}

public FilterResultAndResponse filterBusinessType(Request request) {
    int result = ...;
    Response response = new Response();
    response.setFilteredData(...);
    return new FilterResultAndResponse(result, response);
}

class FilterResultAndResponse {
    private int filterResult;
    private Response response;
    public FilterResultAndResponse(int filterResult, Response response) {
        this.filterResult = filterResult;
        this.response = response;
    }
    // getters & setters
}

3) Solution Overview

The author chose a conservative approach: keep the existing logic but improve documentation, add detailed comments, and share the experience with the team to reduce technical debt.

How to Achieve Simplicity

Product Design

Put users at the center: understand core needs, simplify user journeys, and eliminate unnecessary features.

Apply “subtract‑design”: constantly ask whether a feature is truly needed.

Design intuitive interactions that map naturally to user expectations.

Architecture Design

Avoid chasing flashy technologies; choose what is sufficient and add only one layer of improvement at a time.

Example: expanding a 30‑day calendar to 90 days. The complex solution required extensive data recalculation, while the simple solution reuses the existing 30‑day algorithm and copies the last day for later dates, reducing code changes and storage cost.

Cache usage illustrates the trade‑off between performance gains and added complexity such as consistency and eviction strategies.

API Design

Use standard naming, data formats, and error handling.

Apply the Single Responsibility Principle to keep each API focused.

Minimize parameters and provide clear documentation and examples.

Case: error‑code propagation. Previously, each service wrapped the error, obscuring the root cause. By propagating the original error message, the chain was reduced from five steps to two, improving efficiency.

Code Simplicity

Follow the Single Responsibility Principle.

Avoid redundant code; extract reusable functions.

Comment complex logic.

Break long methods into smaller, focused ones.

Use meaningful variable and function names.

Practical Practices

Automate repetitive tasks with tools.

Document complex business logic thoroughly.

Modularize systems into manageable components.

Standardize components and turn them into fixed processes.

Leverage automation (e.g., deployment orchestration) to reduce manual effort.

Conclusion

Simplifying complexity boosts short‑term development efficiency and long‑term product value. By saying “no” to unnecessary features, unifying terminology, and adhering to principles like KISS and single responsibility, teams create reliable, maintainable software that can continue to innovate.