[* Readable Code * Amazon Purchase Link](https://www.amazon.co.jp/%E3%83%AA%E3%83%BC%E3%83%80%E3%83%96%E3%83 % AB% E3% 82% B3% E3% 83% BC% E3% 83% 89-% E2% 80% 95% E3% 82% 88% E3% 82% 8A% E8% 89% AF% E3% 81% 84% E3% 82% B3% E3% 83% BC% E3% 83% 89% E3% 82% 92% E6% 9B% B8% E3% 81% 8F% E3% 81% 9F% E3% 82% 81% E3% 81% AE% E3% 82% B7% E3% 83% B3% E3% 83% 97% E3% 83% AB% E3% 81% A7% E5% AE% 9F% E8% B7% B5% E7% 9A% 84% E3% 81% AA% E3% 83% 86% E3% 82% AF% E3% 83% 8B% E3% 83% 83% E3% 82% AF-Theory-practice-Boswell / dp / 4873115655 / ref = sr_1_1? adgrpid = 52747835709 & dchild = 1 & gclid = CjwKCAjw2Jb7BRBHEiwAXTR4jcm6iePgNgKHDmEvEtkvsB5IJ_skZ0aSoztpmqccbdEWkPh9VInvSRoC2DQQAvD_BwE & hvadid = 338561722060 & hvdev = c & hvlocphy = 1009309 & hvnetw = g & hvqmt = e & hvrand = 10166295044081564502 & hvtargid = kwd-334307148361 & hydadcr = 16038_11170849 & jp-ad-ap = 0 & keywords =% E3% 83% AA% E3% 83% BC% E3 % 83% 80% E3% 83% 96% E3% 83% AB% E3% 82% B3% E3% 83% BC% E3% 83% 89 & qid = 1600565375 & sr = 8-1 & tag = googhydr-22)
It's not a rough note, but a little detailed note!
Point
It is important to take a step back and ask yourself!
Point
Try to read information just by looking at the name
・ Choose a clear word → Avoid empty words. "Get" is not a very clear word. I don't know where to get?
For example, use fetch / download depending on the situation instead of get.
→ Avoid empty names such as tmp and foo. Give it a name that represents a specific purpose or value. Return value retval × sum_squares○
So, when using a generic name such as tmp / it / retval, be prepared for a good reason! It's nonsense to use this just for negligence! "Naming power"!
→ Use a more appropriate name
→ If it is important information that you absolutely must inform, you can add it to "Variable name". The unit of value is clearer than delay → delay_secs. The same is true in terms of security. password → plaintext_password (password is plain text and should be encrypted before processing)
Add attributes where you need to understand the meaning of variables.
→ It's simply hard to remember, it occupies the screen, and the amount of code increases. A short name is fine as long as the scope is small. If the scope of the identifier is large, the name needs to be packed with enough information to clarify it. It's easy to omit it, but project-specific abbreviations are not acceptable. I can't understand the new members.
→ You can also use underscores, dashes, and capital letters to stuff information into names. The team decides what rules to use. Consistency is important.
For example, underscore class member variables to distinguish them from local variables.
Ask yourself, "Isn't the name mistaken for another meaning?" Actively search for misunderstandings.
Use min and max to include limits.
Use first and last to specify the range.
Use begin and end for inclusive / exclusive ranges.
Clarify the meaning of true and false when choosing the name of a Boolean variable or a function that returns a Boolean value. Dangerous example bool read_password = true; There are two interpretations ・ Password needs to be read from now on -The password has already been read.
Here, it is better to use need_password instead of read.
The first name is that the person reading the code can understand your intentions correctly. Before deciding on a name, make sure that the name is not misunderstood by thinking about dissenting opinions. Also pay attention to the user's expectations for the word. Example: Get () and size () are expected to have lightweight methods.
Three principles • Use a layout that is consistent with the patterns your readers are accustomed to. -Make similar codes look similar. -Make related codes into blocks.
Obviously, a nice looking code is easier to use. If you can scan it quickly, you can create code that is easy for anyone to read.
A good looking code can improve not only the surface but also the structure of the code.
Aligning the columns can make the code easier to read. Doing this will make it easier to find typos.
→ In order to get a quick overview of the code, you can divide it into groups and create "units". Easy-to-understand code.
However, it's important to note that consistent styles are more important than "correct" styles. Even if you write it correctly and easily, if you write it in a disjointed style as a whole, it will be difficult to see and read.
"Shaping" your code in a consistent and meaningful way makes it quick and easy to read.
・ If you are doing the same thing with multiple code blocks, make the silhouette the same person ・ If you arrange the "columns" of the code, it will be easier to get an overview. ・ What was lined up like A / B / C in one place should not be lined up like B / C / A in another place. Choose a meaningful order and always keep that order -Use blank lines to divide large blocks into logical "paragraphs".
Terrible names change names without comment → Comments are not meant to make up for terrible names. If so, change it to a clearer name.
So what should I write as a comment? → Good comments are for "recording your thoughts". You should write "important thoughts" when writing code
You can comment on why the code is dirty. A comment that encourages someone to fix it.
→ Feel free to comment on what you want to do with the code. → Can inform the quality of the code and indicate the direction of improvement.
→ When defining a constant, what does that constant mean? There is often a background as to why they have that "value". → It is important to record in the comments what you thought in your head when you decided on the name of the constant.
Add a comment there to clarify the answer.
→ Predict the problems you will face when using the code in advance and announce them in the comments.
You have to get the new team members to understand the code. How do the classes work together? Such This is a comment to write in the code.
A short, appropriate document is fine. Better than nothing.
Comments that nicely summarize the low-level code are also important.
Write anything that helps you understand the code!
Writer's block = I'm stuck and can't write
The only way to get over this is to start writing. Write down what you think and leave it as a comment. 3 steps to write a comment
The purpose of the comment is to help the reader understand the intent of the code.
・ What can be extracted from the code ・ "Auxiliary comment" to supplement terrible code → Correct the code instead of writing a comment
My thoughts to record · Write why the code looks like this instead of the other way around -Indicate code defects using notations such as TODO :, XXX: ・ Background related to constant values
Think from the reader's point of view ・ Add a comment in anticipation of what the person reading the code thinks "What?" -Document behaviors that surprise the average reader -Write "big picture" comments in files and classes -Comment the code block to summarize it so that the reader is not obsessed with the details.
How can I write it accurately and concisely? Comments should have a high ratio of information to the area.
Should I explain using three lines? → If you can explain in one line, use one line.
I don't know what "it" or "this" means. For example //データをキャッシュに入れる。ただし先にそのサイズをチェックする。 I don't know what "that" means in this case. It's confusing, so it's easier to understand if you put the noun in the pronoun.
//データをキャッシュに入れる。ただし先にデータサイズをチェックする。
Accurate comments and conciseness are often compatible.
Example
//これまでにクロールしたURLかどうかによって優先度を変える ↓ //これまでにクロールしていないURLの優先度を高くする
The bottom is simple, short and direct.
Comments that just write the behavior of the code as it is ✖︎
Write in the comments what you were thinking when you were writing the code. This makes it easy to notice that the code and comments are inconsistent (so-called bugs). Comments play the role of redundancy check.
Write a comment packed with as much information as possible in a small area
・ Avoid pronouns such as "it" and "this" that may refer to multiple things -Explain the operation of the function as accurately as possible -Carefully select I / O examples to include in comments · Code intent is written at a high level, not a level of detail -Use inline comments for unclear arguments. ・ Keep comments concise with words and expressions that are packed with many meanings.
Make the control flow such as conditions and loops as "natural" as possible. Write so that the reader of the code does not stop or read back!
if (length >= 10)
Or
if (10 =< length)
Obviously the first one is easier to read.
There is a guideline for this.
Left side → "Survey target" formula. Change. Right side → "Comparison target" formula. It doesn't change much.
It's the same as English usage.
There are superiority and inferiority in the order
・ Use affirmative system rather than negative condition form. For example, use if (debug) instead of if (! Debug). ・ Write simple conditions first. It is easy to see because if and else are displayed on the same screen. ・ Write the conditions that attract attention or stand out first
Depending on the situation, there may be a conflict, in which case it is at your own discretion.
It has the advantage of being organized in one line, but on the contrary, it is difficult to read and step through with a debugger.
Shorten the time it takes others to understand rather than shorten the number of lines
Some people think that you shouldn't use multiple return statements in a function, but that's wrong. It's good to return quickly from the function.
Deeply nested code is hard to understand. Look at the code fresh when you make changes. Take a step back and look at the whole thing.
Can you follow the flow of execution?
Using components makes it difficult to follow the code. Thread → I'm not sure which code will be executed when. Signal / interrupt handler → Other code may be executed. Exception → Various function calls are about to end
Using these components can make your code easier to read and less verbose, on the other hand. If you don't use it properly, you will lose track of the code.
Divide the huge formula into pieces that are easy to swallow
Watch out for "smart" codes. Later, it becomes confusing when others read the code.
It is difficult to understand a huge formula at once. The easiest way to do this is to introduce "explanatory variables" Explanatory variables that hold the values of large expressions have three advantages ・ A huge formula can be divided · You can document your code by explaining the expression with a concise name · Makes it easier for readers to recognize the main "concepts" of the code
Another option is to use De Morgan's laws to manipulate logic.
If you see complicated logic, split it aggressively!
Delete variable
The code removes variables that are not readable. → The code will be concise and easy to understand.
Reduce the scope of variables.
It is correct to avoid global variables. → It is difficult to track where and how it is used. It's a good idea to "shrink the scope" of all variables, not just global variables.
Reduce the number of lines of code that you can see the variable as much as possible.
It is said that access should be restricted as much as possible to reduce the code that makes variables visible. → Why? Because you can reduce the variables you have to think about at once
Write variable only once
→ Variables that "do not change permanently" are easy to handle.
The more places you manipulate variables, the harder it is to determine the current value.
The variables of the program will increase quickly and will eventually become untraceable Code is easier to read if you reduce variables and make it as light as possible
・ Delete disturbing variables -Make the scope of the variable as small as possible → Move to a position that can only be seen from a few lines of code of the variable. -Use a variable that is written only once → If you set a value for the variable only once (or const,), the code will be easier to understand.
Engineering is the process of dividing a large problem into smaller problems and assembling solutions for each.
This chapter is about actively finding and extracting unrelated sub-problems.
Recommended Posts