Writing Maintainable Code — Reducing Software Complexity Through Modular Design

A key aspect of writing maintainable code is ensuring that developers maintaining the codebase don't need to grasp the entire system at once. Instead, they only need to understand a small portion at a time. When facing unfamiliar code, long code segments require more time to understand. Conversely, well-abstracted code lets maintainers ignore unnecessary details, making it easier to read and improving overall maintainability.

From a technical perspective, this is the essence of "modular design." This article explores what modular design is and what points matter when implementing it.

What is Modular Design?

As mentioned in the introduction, modular design breaks large programs into separate modules that work independently. When executing programs, necessary modules integrate together. This approach means maintainers don't face the entire system's complexity at once, but only the complexity of individual modules.

Specifically, classes, functions, or any abstracted subsystems used when writing programs can be considered modules. Let's look at an example to understand modular design's significance and benefits.

Most frontend and backend engineers have used JSON.stringify at some point in their work. This method on the JSON object converts a value into a JSON string.

Here's an example from MDN documentation:

console.log(JSON.stringify({ x: 5, y: 6 }));
// becomes '"x":5,"y":6'

console.log(JSON.stringify(new Date(2006, 0, 2, 15, 4, 5)));
// becomes '"2006-01-02T15:04:05.000Z"'

From a modular design perspective, the JSON object is a module that lets developers use it without encountering the very complex JSON system underneath.

Most developers who've used JSON.stringify probably think it's a simple method—pass any value in, get a JSON string out. But actually, JSON.stringify handles enormous complexity behind the scenes. Interested readers can check json.org to see JSON's implementation details, which prove far more complex than expected.

For JSON.stringify alone, the stringification process requires:

• Checking if values are valid (for instance, checking for circular references and side effects)
• Handling different value types specially (for example, properly processing escape characters like \n in strings)
• Recursively traversing objects and specially processing each value within them
• Outputting processed results in valid JSON string format

These are just the stringification responsibilities. The process contains many performance optimization opportunities that make implementation especially complex. Google's V8 team even wrote How we made JSON.stringify more than twice as fast detailing how they doubled the method's performance, revealing many considerations developers might never imagine being handled on V8's side.

The key point after all this detail: modular design. Without modularity, developers wanting to convert values to JSON strings would need to first implement all these details. With modular design, developers simply pass a value to JSON.stringify and call it, without facing those tedious details or performance optimizations.

Returning to the modular design definition: through modules, systems break into smaller parts, reducing the scope of concerns for code maintainers from the entire system to manageable pieces, making codebase maintenance far easier.

Core Elements of Modular Design

After understanding modular design through concrete examples, let's examine its core elements.

Observing the examples mentioned above, modules can break down into two parts: interface and implementation. The interface describes how to use a module and interact with it. The implementation details how the module actually works through code.

More specifically, the interface is like the module's user manual. For a function, the interface includes what parameters it accepts and what output it produces. For code maintainers using a module, the interface is the only information they need. Sometimes using a module requires additional explanation (through comments or documentation), which becomes the informal interface.

The implementation is the module's actual code, but this part doesn't need maintainers' focus. Taking JSON.stringify as an example: maintainers only need to know the interface, not the complex implementation details underneath. This makes maintenance far easier.

Read More

For deeper insights into implementing good modular design and other related points, our E+ growth plan topic articles contain more detailed discussions. Interested readers are welcome to join E+ to explore further (link).