Notes find a misplaced and useless in the code is not very interesting? How would you do write a few comments but still make the code easier to understand?
One major way is to make the code self-documenting. When the code is self-documenting, when you do not need to comment on its role or purpose, and also makes the code much easier to maintain.
In this article, I will provide to make your code self-documenting way. The following three kinds of such basic method code is self-documenting:
Naming: to explain the purpose of variables, functions, and so the use of the name.
Wrapper function: the function of specific code is encapsulated into a function to clear purpose.
Variables introduced: the expression is inserted into the private variable.
It may seem simple, but in actual operation will make people feel a bit tricky. First you have to understand what problem areas and, where applicable, which of these methods. In addition to these three, there are used widely in the way:
Class and module interface: The class of functions and modules are exposed, make the code more clear.
Code groups: a group of codes to distinguish between different segments.
Next we will be by way of example, specific to talk about how to use the five methods in practical applications.
One, named
First of all, look at how few use the code name became clear and self-documented examples.
- Rename function can abide by the following rules.
Avoid using vague words like "handle" or "manage" - handleLinks, manageObjects.
Use active verbs - cutGrass, sendFile, to indicate the function performed actively.
Return Value Specifies the type - getMagicBullet, READFILE. May be strongly typed language to indicate the type of return value of a function type identifier.
- Rename the variable.
Designated units - if there are numerical parameters, it can be combined with the unit. For example, instead of using widthPx width to the specified width in pixels.
Do not use the shortcut keys - a and b can not be used as the parameter name.
Second, the function package
Next, look at a few examples of how the code encapsulated into function. One benefit of encapsulation is to avoid code duplication function, structure or improve code.
- Encapsulated into function code.
This is the most basic: encapsulated into function code to clarify its purposes. Guess this line of code is doing:
var width = (value - 0.5) * 16;
Seems not very clear, of course, there is a clear picture comments, but we can package into function in order to achieve self-documenting, as follows:
var width = emToPixels(value);
function emToPixels(ems) {
return (ems - 0.5) * 16;
}
The only change is the calculation process was transferred to a function inside. This name clearly expressed what it needs to do, such an action would not have to write a comment. Moreover, if there is need later you can also call this function directly, serve two purposes, to reduce duplication of effort.
- Conditional expression instead of using the function.
If the statement if it contains more operands, do not write comments to mean that it is more difficult:
if(!el.offsetWidth || !el.offsetHeight) {
}
Know the purpose of this code is not above? Replaced as it is not:
function isVisible(el) {
return el.offsetWidth && el.offsetHeight;
}
if(!isVisible(el)) {
}
Third, the introduction of variable
Finally, talk about how to introduce variables. Compared to the above two methods, this may not be so useful, anyway, know better than I do not know.
- Instead of expressions with variables.
Consider the following example:
if(!el.offsetWidth || !el.offsetHeight) {
}
This is a function of the package is not replaced by the introduction of variables:
var isVisible = el.offsetWidth && el.offsetHeight;
if(!isVisible) {
}
- Instead of equations with variables.
It can also be used to clearly explain complex program:
return a * b + (c / d);
With variable instead:
var divisor = c / d;
var multiplier = a * b;
return multiplier + divisor;
Four, classes and interfaces module
Interface classes and modules - also for the public methods and properties - a bit like how to use the documentation. See the examples below:
class Box {
public function setState(state) {
this.state = state;
}
public function getState() {
return this.state;
}
}
This class can also contain other code. I deliberately cite this example to illustrate how common interface self-documenting. Can you name this class is how it is called? Obviously, this is not obvious.
Both of these functions should change the name in order to express their legitimate purpose. But even to do this, we are still not very clear how to use. Then you need to read more code or read documents. But if we change this a little bit?
class Box {
public function open() {
this.state = open;
}
public function close() {
this.state = closed;
}
public function isOpen() {
return this.state == open;
}
}
Is not it more clear? Note that we only change the public interface, the internal representation of the original this.statestate of the same.
Fifth, the code packet
Used to distinguish one form set different pieces of code are self-documenting. For example, as the article said, we should define variables as close as possible to use it, and as far as possible the variable categories. This can also be used to specify the relationship between the different code groups, so more convenient others know what they need to know the code group. See the examples below:
var foo = 1;
blah()
xyz();
bar(foo);
baz(1337);
quux(foo);
Compared with the following:
var foo = 1;
bar(foo);
quux(foo);
blah()
xyz();
baz(1337);
Will fooall use combinations put together, at first glance you can know all kinds of relationships. But sometimes we have to call some other functions in the middle. So if you can then try to use the code grouping, if not, then do not insist.
Six other recommendations
Do not use strange mark, the following two are equivalent:
imTricky && doMagic();
if(imTricky) {
doMagic();
}
Obviously the latter is better. Grammar skills and did not do any good.
Named constant: If the code there are some special value, it is best to give them names, such as var PURPOSE_OF_LIFE = 42.
Rules: best to follow the same naming rules, so people will be able to read correctly guess the various meanings of things in reference to the other code.
Reproduced source https://colobu.com/2014/12/23/How-to-make-your-code-self-documenting/
English original http://codeutopia.net/blog/2014/12/01/how-to-make-your-code-self-documenting/
Reproduced in: https: //www.jianshu.com/p/f55a8fdc6024