CHAPTER 3: Functions
Summary:
This chapter introduces how to write functions effectively. It explains how to implement a function that clearly expresses the intention, and what properties to give to the function so that a first-time reader can intuitively understand the purpose of the program. Following is the list of rules for writing functions effectively that the book suggests.
Function should be made as small as possible. The smaller the function, the easier it is to understand.
Only one logic should be performed in each function.
Set one level of abstraction per function. If a function is mixed with code of different levels of abstraction, it causes poor readability.
A smaller number of parameters is preferable. The ideal number of parameters is 0.
Flag arguments should be avoided if possible, as this indicates that the function is performing multiple tasks at once.
Parameters should not be output values.
Switch statement should be hidden inside the abstract factory.
Give your functions descriptive names. Having a long name isn’t a problem. A long, descriptive name is better than a short, difficult one.
Use exceptions rather than returning error codes.
Writing software is similar to writing any other text. It is common for writers to first record their thoughts and then refine them. Programmers should write functions in the same way. At first, it can be long and complicated. Loops may overlap, names may be improvised, and codes may be redundant. However, with the rules listed above, programmers will be able to refine, rename, remove duplicates, and finally arrive at a clean functions.
Experience:
When I read the code in Listing 3-7 presented by the author as an example of a desirable function, it was amazing that I could understand everything immediately after I just followed the code flow. Without having to worry about what each variable means or what the function does, I was able to figure out the flow and relationships of the function right away. I could feel the traces that the author put a lot of thought into making this piece of code like a well-written article.
In this chapter, the content of the subsection ‘Don’t Repeat Yourself’ was especially relatable to me. In a recent project, I wrote several overlapping functions that are slightly different but actually perform the same logic. While writing it, I remember blaming myself for whether this redundant, dirty code was my best. So far, I wanted to fix this redundant codes, but I didn’t have enough time and didn’t know the right way to fix, so I neglected it. Now that I have read and learned the guide to writing clean functions, I think I can improve my code by actively referring to it.
On the other hand, I was a little worried because I had never written such neat code. I wondered how much time I would have to invest to write such good code, and furthermore, I wondered I could actually write code like this while working in real life. In practice, when I listened to the intern experiences of my acquaintances, there were quite a few people who said that the code that had already been written was so messy that it took several months to understand and fix it. I thought it would be nice to be given an environment and resources that can realistically produce high-quality results.
The author says that these codes are not created at once, but are obtained only after going through the process of trimming, changing, and fixing. Seeing that the author of the book Clean Code also said this, it seems that the ability to write clean code is not easily acquired. I felt the need of investing a lot of time and make an effort to improve my codes into clean codes, rather than just reading the book and skipping it.
CHAPTER 4: Comments
Summary:
Comments are used for the purpose of explaining content in programming. Its main purpose is to make source code easier to understand, and it is useful when collaborating. However, the book states that poor code quality is one of the most common reasons for adding comments. Code that is simple, uncluttered, and lightly commented is better than code that is complicated, cluttered, and heavily commented. Rather than trying to explain in comments, programmers should spend time cleaning up that mess.
There are two types of comments: good comments and bad comments. Good comments include legal comments, comments explaining intent of a function, comments that provide information, comments that clarify meaning, comments that warn consequences, TODO comments, and comments that highlight importance. Bad comments include reluctantly written comments, repeating comments, comments that can be misunderstood, obligatory comments, comments that record history, comments that contain too obvious facts, comments that can be expressed with variables/expressions, comments that indicate locations (e.g. ////from here////), and comments that provide too much information.
It is important to note that comments do not make up for bad code. Longer comments indicate that your code is less readable. If comments are getting long, programmers should consider refactoring or rewriting the code. Clean code are the code that can be read without comments expressing the intent of the program.
Experience:
I got used to working in collaboration with many people while participating in various projects. So until now, I always wrote long comments in my code so that others can see and use my code comfortably. I wrote who wrote the code, why it was made, how it works, which parameters are what form, and even the logic flow was written case by case. And I considered myself to be meticulous in my work. Nevertheless, the book points out that my inability to explain my intentions with code and manage them with comments poses a problem. I have learned that what I want to say must be expressed solely in code, and that I may only write comments in regards to my intentions or information that cannot be expressed in code. To become a competent developer, I must devote a great deal of time and effort to learning how to tell stories by coding rather than commenting every word.
CHAPTER 5: Formatting
Summary:
Orderly, clean, and consistent code gives people the impression that it was written by an expert. Conversely, if code looks cluttered, people will think that programmer wrote it in a careless manner throughout the project. As a programmer, it is important to write code in a neat format. Code formatting is part of communication, and communication is the primary duty of professional developers. The purpose of conforming to the format is that even after a long time has passed and the code has changed so much, the initial implementation style and level of readability continue to affect maintainability and scalability of the program. Programmers should establish simple rules to match the code format, and follow those rules diligently throughout the project. If you work as a team, the team should agree on one formatting rules, and everyone should follow them. If necessary, use tools that automatically apply rules. The following are the five guidelines provided by the book for formatting code.
The first rule for formatting code is to keep proper line lengths. How long should the source code be? Large systems can be built with files no more than 500 lines, most of which are around 200 lines. In practice, professional Java projects (JUnit, FitNesse, Time and Money, etc.) are implemented this way. Limiting code length to 200 lines is not necessarily a hard rule to follow, but it is generally easier to understand small files than large files.
The second rule is to write code like a newspaper article. A good newspaper article has a headline at the top (a phrase that summarizes the article in a few words), and a summary of the entire article in the first paragraph. Similarly, source file names (headings) should be made simple and descriptive so that reader can determine whether they are looking at the correct module just by looking at the name. Also, the first part of the source file (summary) has to describe high-level concepts and algorithms, and as it go down, it should describe intent in detail, and finally end with the lowest-level functions, such as getters/setters. No one would read a newspaper if it published just one long story with a random agglomeration of facts, dates, and names.
The third rule is to separate the codes by blank lines. Each line of code represents a part of a concept, and a group of lines represents a complete idea. You should put a blank line between concepts to separate them. Otherwise, the readability of the code will be significantly reduced.
Fourth, if line breaks separate concepts, conversely, vertical density means association. That is, lines of code that are dense with each other should be placed vertically close together. If two concepts belong to different files, the rule does not apply, but if there is no valid reason, concepts that are close to each other should belong to the same file (it is the reason to avoid protected variables). Expresses the degree to which another concept is important to the understanding of one concept.
The fifth is the rules for variables and functions. Since our function is very short, variables should be declared as close as possible to where they are used, and instance variables should be placed in one place. Also, if one function calls another function (a dependent function), put the two functions vertically close together. If possible, place the called function after the calling function. If you apply these rules consistently, your code will become more readable, and the reader will naturally expect that the function just called by the function will be defined shortly after.
Finally, the chapter ends by explaining the team rules. If you are on a team, your first priority and preference is the team rules. Teams must agree on one rule, and all team members must follow those rules. This ensures that the software exhibits a consistent style. If the team was formed for the first time, before starting coding, discuss the coding style, decide where to put parentheses, how many characters to indent, how to name classes, variables, and methods, etc. A good software system should be easy to read. Style should be consistent and sleek. It should give the reader confidence that the format seen in one source file is also used in another source file. The mistake of making the source code more complex than necessary by mixing all kinds of styles must be avoided.
Experience:
Formatting is essential while programming, and in particular, I think the team rules explained at the end of the book are very important. I am currently working on a project to create an Android mobile app in the course and feel the importance of formatting. While working on this project, my team coded without setting up team rules before starting coding. In the recent milestone, we had to implement providing weather and map information to the user, and we divided into two teams to work on each. Each team successfully implemented their respective feature, and finally it was time to merge the completed codes one last time. However, each team’s code format was completely different. The variable and function names were different, the functions that required similar logic were written in very different forms, and the readability of the code was bad. Therefore, we had put effort into merging the code by asking each other their implemented codes. Then, there was a button with the same ID in the codes written by each team, and we had to resolve the conflict. Our work would have been much easier and more efficient if we had decided on a format before we started coding.
