Simplifying Complexity: Principles and Practices for Cleaner Software Design

Background

Recent development work revealed that a historical feature had become unnecessarily complex from both product and technical perspectives, reinforcing the core idea that simplifying complexity is a perpetual challenge in product design and software development.

The classic "Mythical Man‑Month" distinguishes essential complexity (inherent to the problem) from accidental complexity (introduced by poor choices or methods).

Why Simplicity Matters

Simplicity is not about superficial ease but about reducing overall system intricacy, making the product easier to understand, maintain, and evolve.

Case Details

Product Design Issues

Multiple business types (e.g., Promise business, document types, operation types) map one‑to‑one, creating redundant terminology and conversion logic that could be unified.

Code Issues

Side effects in methods such as filterBusinessType modify the response object while also returning an int , leading to long call chains and maintenance difficulty.

public int filterBusinessType(Request request, Response response) {
    if (...) {
        return ...;
    }
    boolean flag = isXXX(request, response);
}

Correct approach emphasizes clear separation of concerns and ordering of side‑effect operations.

public int filterBusinessType(Request request, Response response) {
    /**
     * Return must occur after isXXX modifies response.
     */
    boolean flag = isXXX(request, response);
    if (...) {
        return ...;
    }
}

Thought Points

Avoid over‑abstraction that adds hidden complexity.

Adopt layered architecture where each layer only depends on the one directly below it.

Merge duplicate code into reusable utilities.

Establish team consensus and coding standards to enforce simplicity.

Side‑Effect Management

Make side effects explicit in method names or documentation.

Avoid static mutable state when possible.

When unavoidable, encapsulate results in a composite object.

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 and setters
}

KISS Principle

Design should be as simple as possible, avoiding unnecessary features that increase maintenance burden.

Product Design Recommendations

Focus on user‑centered design, simplifying user journeys.

Apply "subtract‑design" by questioning the necessity of each feature.

Ensure intuitive interactions and continuous iteration based on feedback.

Architecture Design

Prefer simple, sufficient architectures over flashy, overly complex stacks; avoid introducing new frameworks that add more complexity than they solve.

Minimal API Design

Expose the smallest possible set of methods and parameters, adhering to the single‑responsibility principle, to make APIs easy to understand and evolve.

Code Simplicity Practices

Follow single‑responsibility principle.

Eliminate redundant code through abstraction.

Use clear comments for complex logic.

Break long methods into smaller, focused functions.

Choose meaningful variable and function names.

Automation and Standardization

Transform repetitive tasks into tools, standardize components, and automate workflows to reduce manual effort and error rates.

Conclusion

Simplifying complexity improves short‑term development efficiency and long‑term product value; it is not laziness but a disciplined approach to delivering reliable, maintainable software.