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.
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.
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.
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.
Bad comments can hurt the clarity of your code. There are also good comments to add to the clarity of your code.
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.
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.
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.
Proper code formatting (i.e. keeping lines short, adding blank lines etc.) on the other hand helps a lot with reading and understanding code.
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 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
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.