Clean Code: The Power of Writing Meaningful Comments - Part 2

Part 2 of our ongoing series on clean code delves deeper into the principles that make code easy to read, understand, and maintain. In this installment, we focus on techniques for naming variables, functions, and classes, and explore how to structure code in a way that makes it easy to navigate. We also discuss the importance of writing small, focused functions, and avoiding code duplication. By following these principles, you can create code that is not only easier to write, but easier to read, understand,

Posted by Saportif Technology on

Comments

In general, most people think that comment lines make the code more understandable. But it could also be the other way around. Commenting lines in your code can be confusing and less understandable.

Bad Comments

There are many bad comments you can add to your code. These comments can sometimes be confusing or even misleading.

 

 

Dividers & Markers

If you've written your code clean enough, dividers and markers are unnecessary. You do not need to add an extra divider and marker. They just complicate the readability and flow of your code.

 

 

Redundant Information

If your code is very clear and understandable, like in this example, the comment is useless. It just wastes time reading. If the naming you use in your code is not clear enough, you can use comments here, but of course you should avoid bad naming first.

 

 

Commented Out Code

In this way, we do this from time to time to comment out our code. But delete it instead. If you are using version control software (eg Git) you can get your codes back when needed.

 

 

Misleading Comments

It is very likely that this comment line will confuse the person reading the code. Because the function name is createAdmin, but it is written next to it as a comment to create a new user. So, does this function create admin, create a user or create a user in the admin property? At this point, the comment is confusing and complicates things even more. Such comments should be strictly avoided.

 

 

Good Comments

Bad comments can hurt the clarity of your code. There are also good comments to add to the clarity of your code.

 

 

Required Explanations

In this example the naming is clear and we can understand that it defines the rules for a valid password, but the rules are not that easy to understand. This is exactly where comments come into play and provide understanding of the rules.

 

 

Warnings

Although we do not come across it very often, sometimes warnings like this example may be required. Warnings that indicate what the code to run at that moment needs or the code will wait there and this will take time make our job easier.

 

 

Todo Notes

You can add todo notes from time to time so that you don't forget future features in your code or to show your colleagues what to do where in the code, this will make your job easier. Of course, you should not overdo it. If you leave todo notes everywhere, your code will become quite complex and will not help you.

 

 

Formatting

Proper code formatting (i.e. keeping lines short, adding blank lines etc.) on the other hand helps a lot with reading and understanding code.

Vertical Formatting

As the name suggests, vertical formatting is about using vertical space in your code file. That is, it's about adding blank lines in the right places, grouping related concepts together, and leaving space between distant concepts.

 

 

Adding Blank Lines

Let's take a look at this example:

Although the code above has good naming and is not very long code, it is quite difficult to read due to no spaces and no grouping. It will be easier to read if we format this code as follows:

It is the exact same code but the extra blank lines help with readability. Hence you should add vertical spacing to make your code cleaner. But where should you add blank lines? That's related to the concept of "Vertical Density" and "Vertical Distance".

Vertical Density & Vertical Distance

The concept of vertical density implies that related concepts should be kept together. The concept of vertical distance, on the other hand, means that concepts that are not closely related should be separated. This affects the intelligibility of both individual statements within a function and group statements/methods/methods as a whole.

 

 

Ordering Functions & Methods

It is good practice to "stepdown rule" in sorting operations. A function A which is called by function B should be (closely) below function B - at least if your programming language allows such an ordering.

 

 

Horizontal Formatting

Horizontal formatting is about using horizontal spacing in your code file. This means that lines should be short and readable.

 

 

Breaking Lines Into Multiple Lines

Of course, you can fit very long lines of code on your screen, but this will harm the readability of your code. For good, readable code you should use relatively short lines, if it's too long you should consider splitting the code into short lines.

That was too long and too much code in one line. Without changing the logic of the same code, we can write it more clearly as follows:

 

 

Using Short Names

We talked about the need to be descriptive when naming. But while being descriptive, we should not be too specific and prolong the naming unnecessarily.

For example, instead of saying createUserWithUniqueUserNameAndEmialAndPassword when defining a function, it would be sufficient to just say createUser.



Clean Code is a very important and comprehensive topic. Two of the sections included in this scope are Comments and Formatting. The comments you use in your codes should make the code more understandable instead of confusing the code. Therefore, it is very important how you will use comments. Another issue that increases the readability of your code is formatting. While writing your code, you should pay attention to what formatting method you will apply and improve your code accordingly.