[Ruby] Basic rules to keep in mind when writing readable code

4 minute read

Premise
This is a summary of what I have learned just after programming (1 to 2 months).
There may be things that are not valid or incorrect in the actual field,
If you notice any, please feel free to report in the comments.

I, a beginner in programming,

Need to write readable code
How to write clear code

I have summarized what I have learned about.

Why you need to write readable code

There are three main reasons for writing readable code. ・Increases productivity of individuals and organizations ・Maintenance improves ・Flexible development system can be built Basically, the development by programming is done by multiple people, so if you write the code that you only need to know yourself, productivity will peak and you will be far from a flexible development system.

Refactoring is done to realize these three. What is refactoring? To improve the readability of the source code without affecting the implemented functions. This refactoring makes it easier for people who work with us to understand and modify the implemented code.

Points to be aware of when actually writing code

Variables are named in consideration of others (names of variables and functions) Easy to read without complicated logic (simplification of logic) Comments are written, and the code can be read while grasping the whole picture (correct and straightforward comments)

Variable and function naming

When naming variables and functions, avoid abstract names and give them concrete names. For variable name Define it so that you can understand what role the variable has. For function name Define in the form of verb + noun so that you can understand what to do and what to do.

Example of variable name

bad example

const one = 1;

Good example

const userId = 1;

In a bad example, the name of the variable one does not tell what the value of 1 is and what role it has. In a good example, the variable is userId, and you can see at a glance that the value 1 is the user ID.

Function name example

bad example

const add = () => {
processing
};

Good example

const addTask = () => {
processing
}

In the bad example, I know I’m adding something, but I’m not sure what to add. In a good example, Task is attached, so you can understand at a glance that it is a process to add Task.

Simplified logic

There are two major factors that complicate the code. If there is a nest description in the nest When the conditional expression is complicated

If there is a nest description in the nest

What is Nest? Nest is a nested structure. When compared with a conditional expression, it is said that there is a deep nest when an if is written inside an if, and if is further written inside that if. This means that it contains many nested structures.

As you can see from this example, the more the number of structures in one structure, the more complicated the structure becomes. In other words, it is easier to see the code of nesting as much as possible while nesting. Specific measures ・Return the return value at an early stage, and divide the process into subdivisions.

  • Use logical operators.

When the conditional expression is complicated

Even if the conditional expression is long, it is difficult to understand because you have to read it from the beginning to the end to understand the contents of the process.

If the description of the conditional expression becomes long, you can make the code simpler and easier to understand by writing the conditional expression as a function and calling the description.

Still, the description is complicated because there are multiple conditional expressions in the first place. In that case, you can simplify the description by decomposing multiple conditional expressions and dividing them into multiple ifs.

Communicate accurately with comments

You can leave comments in the code by commenting out. You can use this comment to make the description easier to read.

When to leave a comment

・If you write complicated logic, leave a summary of the process and your thoughts in the comments ・Leave why you have such a description

When you should not leave a comment

・Supplementary comment of comment ・”Auxiliary comment” to supplement code that is too complicated to process Comments are left as annotations in the first place, so reading a lot of comments is not concise code. In addition, the process may be too complicated to be covered by one comment. In these cases it is important to fix complex source code rather than relying on comments.

This is the basic rule to be aware of when writing easy-to-understand code I learned as a beginner in programming. If you have any additional notes or corrections, please leave a comment.