How to write maintainable code efficiently?

The original: How to make your code self-documenting?

How do I make the code self-documenting?

Translator: Dwqs

Isn't it interesting to find a misplaced and useless comment in your code?

How do you write very few annotations but still make the code easy to understand?

One major way is to make your code self-documenting. When the code is self-documenting, it doesn't need to comment on its role or purpose, and it makes the code very easy to maintain.

In this article, I'll provide some ways to make your code self-documenting. Here are three basic ways to make your code self-documenting:

• Naming: The purpose of explaining variables, functions, etc. by name.
• Encapsulation function: Encapsulates the code of some specific functionality into a function for explicit purposes.
• Introduce a variable: Inserts an expression into a private variable.

This may seem simple, but it can be a bit tricky to do during the actual operation. First you need to understand what is wrong and where to apply these methods.

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

• Class and Module interfaces: exposes the functions in classes and modules to make the code clearer.
• Code grouping: Use groups to differentiate different snippets of code.

Next, we will use the example to explain how to apply the above 5 methods in practical application.

First, the name

First, take a look at a few examples of how to use naming when code becomes clear and self-documenting.

1. Renaming functions

It is not difficult to name a function, you can follow the following rules:

• Avoid using vague words, such as "handle" or "Manage"--handlelinks, manageobjects.
• Use the active verb--cutgrass, sendFile, to indicate that the function is actively executing.
• Specifies the return value type--getmagicbullet, READFILE. A strongly typed language can also use a type identifier to indicate the return value type of a function.

2. Renaming variables

• Specify the unit-if there is a numerical parameter, it can be added to the unit. For example, using WIDTHPX instead of width to specify the width of the units is pixels.
• Do not use shortcut keys--a and B are not allowed as parameter names.

Second, function encapsulation

Next, take a look at a few examples of how to encapsulate code into functions. One of the benefits of encapsulating a function is to avoid code duplication, or to improve the code structure.

1. Encapsulate the code into functions

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

It doesn't seem clear, of course, there are annotations, but we can encapsulate them into functions for self-documenting ...

var  function emtopixels (EMS) {    return (ems-0.5) * 16;}

The only thing that changed is that the computational process was transferred to a function. The function name explicitly expresses what it is doing so that it does not have to write a comment. Furthermore, if there is a need to call this function directly later, double benefit reduces duplication of effort.

2. Replacing conditional expressions with functions

If a statement contains more than one operand, it is difficult to understand if the comment is not written.

function isVisible (EL) {    returnif(!isvisible (EL)) {}

Iii. Introduction of variables

Finally, let's talk about how to introduce variables. This may not be so useful compared to the two methods above, but it is better to know than not to know anyway.

1. Replace the expression with a variable

Take a look at the example above

var isVisible = El.offsetwidth && el.offsetheight; if (!isvisible) {}

2. Replacing equations with variables

We can also use it to clearly illustrate complex programs:

Replace with a variable.

var divisor = C/D; var multiplier = a * b; return multiplier + divisor;

Iv. class and Module interfaces

The interfaces of classes and modules--also public-facing methods and properties--are somewhat like documents that describe how to use them.

Look at the following example:

class Box {public     function setState (state) {This] state        = state;    }     Public Function GetState () {        returnthis. State;    }}  

This class can also contain other code. I specifically cite this example to illustrate how the public interface is self-documenting.

Can you tell how this class is called? Obviously, it's not obvious.

Both of these functions should be given a reasonable name to describe their purpose. But even if we do, we don't know how to use it. Then you need to read more code or flip through the document.

But if we change it this way ...

class Box {public     function Open () {This] state        = open;    }      Public Function Close () {This        . state = closed;    }     Public Function IsOpen () {        returnthis. state = = open;    }}  

Is it much clearer? Note: We just changed the public interface, and its internal expression is the same as the original this.state state.

Five, Code grouping

Using groups to differentiate between different snippets is also a form of self-documenting. For example, as stated in this article, we should, as far as possible, define variables close to where they are used, and categorize variables as much as possible. This can also be used to specify relationships between different code groups, which makes it easier for others to know which code groups they need to know.

Look at the following example:

var foo = 1; Blah () xyz (); Bar (foo); Baz (1337); Quux (foo);

Compare to the following:

var foo = 1;bar (foo); Quux (foo); Blah () xyz (); Baz (1337);

Put all the use combinations of Foo together, and you'll know all kinds of relationships at a glance. But sometimes we have to call some other functions in the middle. So if you can then try to use code grouping, if not, then do not insist.

Vi. Other recommendations

• Do not use strange markings, the following two are equivalent

if (imtricky) {    domagic ();}

Obviously the latter is better. Grammar techniques do not bring any benefit.

• Named constants: If you have some special values in your code, it's a good idea to name them. var purpose_of_life = 42;
• Make rules: It's best to follow the same naming conventions. This way the reader can correctly guess the meaning of various things based on the reference to other code.

Original starting: http://www.ido321.com/1360.html

How to write maintainable code efficiently?