How to Write Maintainable Code Efficiently?

❮ Verilog Loop Cpp Keyword Intro ❯

Category Programming Techniques

Isn't it amusing to find a misplaced and useless comment in the code?

How can you write with minimal comments but still make the code easy to understand?

A primary method is to make the code self-documenting. When the code is self-documenting, there is no need for comments to explain its function or purpose, and it also makes the code very easy to maintain.

In this article, I will provide some ways to make your code self-documenting. The following are three basic methods to make your code self-documenting:

Naming: Use names to explain the purpose of variables, functions, etc.
Encapsulating functions: Encapsulate some specific functional code into a function to clarify the purpose.
Introducing variables: Insert expressions into dedicated variables.

This may seem simple, but it can be a bit tricky in practice. First, you need to understand where there are problems and where these methods apply.

In addition to the above three, there are some more widely used methods:

Class and module interfaces: Expose the functions in classes and modules to make the code clearer.
Code grouping: Distinguish different code segments using groups.

Next, we will discuss through examples how to apply the above five methods in practical applications.

One, Naming

First, let's look at some examples of how to use naming to make the code clear and self-documenting.

1. Renaming functions

Naming functions is not difficult; you can follow these rules:

Avoid vague words such as "handle" or "manage"—handleLinks, manageObjects.
Use active verbs—cutGrass, sendFile, to indicate that the function is actively performing.
Specify the return value type—getMagicBullet, READFILE. Strongly typed languages can also use type identifiers to indicate the return value type of the function.

2. Renaming variables

Specify units—if there are numerical parameters, you can add their units. For example, use widthPx instead of width to specify that the unit of width is pixels.
Do not use shortcuts—a and b should not be used as parameter names.

Two, Function Encapsulation

Next, let's look at some examples of how to encapsulate code into functions. One advantage of encapsulating functions is to avoid code duplication or to improve the code structure.

1. Encapsulating code into functions

This is the most basic: encapsulate code into functions to clarify their purpose. Guess what the following line of code does:

var width = (value - 0.5) * 16;

It's not very clear, of course, with comments, it's very clear, but we can encapsulate it into a function to achieve self-documentation...

var width = emToPixels(value);

function emToPixels(ems) {
    return (ems - 0.5) * 16;
}

The only change is that the calculation process has been moved to a function. The function name clearly expresses what it does, so there is no need to write comments. Moreover, if needed, this function can be directly called later, killing two birds with one stone, reducing repetitive work.

2. Using functions instead of conditional expressions

If statements containing multiple operands are difficult to understand without comments.

if(!el.offsetWidth || !el.offsetHeight) {
}

Do you know the purpose of the above code?

function isVisible(el) {
    return el.offsetWidth && el.offsetHeight;
}

if(!isVisible(el)) {
}

Three, Introducing Variables

Finally, let's talk about how to introduce variables. Compared to the above two methods, this may not be as useful, but in any case, it's better to know than not to know.

1. Using variables instead of expressions

Look at this example

if(!el.offsetWidth || !el.offsetHeight) {
}

Now, instead of encapsulating into a function, use introducing variables to replace

var isVisible = el.offsetWidth && el.offsetHeight;
if(!isVisible) {
}

2. Using variables instead of formulas

We can also use it to clearly explain complex programs:

return a * b + (c / d);

Replace with variables

var divisor = c / d;
var multiplier = a * b;
return multiplier + divisor;

Four, Class and Module Interfaces

The interfaces of classes and modules—also the methods and properties facing the public—are a bit like documentation on how to use them.

Look at the following example:

class Box {
    public function setState(state) {
        this.state = state;
    }

    public function getState() {
        return this.state;
    }
}

This class can also contain

❮ Verilog Loop Cpp Keyword Intro ❯