Hello,
In this post, I will share my understanding on the Part-1 of the book "The Art of Readable Code" by Dustin Boswell and Trevor Foucher.
General
The book explains various tactics that can be acquired by a programmer to master the art of writing a readable code. While a programmer considers different technical aspects of project such as Run time, memory usage, DB design and so on, the authors have emphasized on a completely normal but important factor. They stress on the 'time-taken by another person to understand your code'. According to the author, this is also a very important factor to be considered during any development. When done continuously, it will become a practice and your end coding will improve.
1. Surface-Level Improvements
General factors like better understandable names, comments and white spacing throughout helps the reader to understand your code better and faster.
Regarding naming a variable, rather than being generic, it’s always better to think specific to your usage or application. When it comes to function names, try to make the name like a small comment explaining what the function is doing. The authors have suggested many options to use in the places of general function names like "send/find/start/make".
The authors are agreeing with the use generic names in opt places. The example they suggested is when most programmers use the word "temp" when performing a swap or to hold a temporary value or file.
Next, the authors have suggested better ways for variable naming in terms of loops. It is a common practice to use i/j/k/so on when it comes to loop variables. The authors have suggested to take time and use a loop variable with respect the program. Such as using lay1/lay2 or dim1/dim2 when traversing through a multi-dimension array.
It is always good to attach more information or important information into your variable name. The authors have explained it as, rather than using a simple variable like "size" for holding the size, we can add information like "file_size or size_MB" or so on. Be careful to reveal only general information about the variable and not any crucial information of the project.
The authors suggesting to go with better explaining names for the variables rather using an acronym or abbreviation. Over the time, it possible that even the same developer might not understand the variable used. Be sure to use a self-explaining name for variables and functions, even if it gets a bit longer. As always, think from another person perspective when writing the code, the size and number of lines is important as well as the end product being easy to understand.
Another well explained example in the book is when normally programmers use the word filter, does it select or remove a certain specified data from a pile. It is good to go for a more concrete word in this case depending on your usage.
Another import naming aspect is regarding boolean. It is always good to avoid naming the variable in a negated aspect, such as "not_valid". It is good to come up with different names and weigh the benefits of each word.
2. Aesthetics or Appearance of the code
The way you represent and arrange your code helps greatly to understand it better. Be consistent in how you write your code with respect to the use of tabs, white-spaces, _ in variable names, etc. There are different ways to accomplish this, if it’s a vast project follow or decide a methods and stick to it throughout the project. Even if it’s a single page/function it is always good to spend some time and arrange it properly. The end product of the check will be easier to maintain and reuse in future.
- The authors are also suggesting to view coding like writing a normal text, with separation on paragraph level. Start with headers or includes, defining the variables, reading variables or setting values, validate the inputs, actual computation and output.
3. Comments
It is important to decide when/what to comment and not to. As always view from another person perspective or new-comer to the project to see how good your comment is. The need for the comment is to help a person traverse through your code reading these comments and get a general picture of the program.
This is habit which will improve as you do, hence, even if you are not good at beginning level, start commenting about your thoughts of the function. As you work on, you will realize your commenting ability has been improved greatly from the beginning. Remember, the developer knows so much about the project/one’s own function at the beginning, but after release the same developer might find it hard to understand certain parts.
Try to answer anticipated default question when your comment, especially in functions. If there are any points inside the function or about a variable to be careful, mention it on the comments.
Just like naming the variable, it is good to have the comments be precise, concrete and not general. When you develop the function, you will know all the points about the functions, what is the input, what is an error, what is the computation, what will be outputted. Try to mention all the important points when write the comment.
It is also encouraged to write in-line comments within the function or across a variable or condition to better explain the code.