Code Comment and How to do it properly
What is code comment ?
Code comment is a small description normally above or next to the code line which it present for. Normally, Code comment is used to describe a complicated algorithm or code which is hard to read and understand.
Why do we need it ?
Code comment can be considered to be annoying, time-wasting with no benefit but it actually helpful when the responsible developer is away due to his/her personal problems and no one know how or what exactly the business is related to the problem.
And remember even if the developer are good at code reading, reading a complex code line without code comment will cost them a lot of time and still be misleading by code sometimes which can lead to disaster later.
So Code comment is a good way which can help us to easily understand the code flows when urgent thing comes up
In conclusion, we should think of code comment like this “Inconvenience at first, convenience later”.
How to do it properly?
Firstly, we need to know what is improper code comment in order to create a proper one.
So what is improper code comment ?
Improper code comment is a comment that are not too helpful for the reader when they come to read it so reader have to read again or dig deeper in order to understand the flows afterward
For example
As you can see, with the code comment above, user might be able to understand that he will be able to have query string but the point turn out is if he want to understand for more he have to dig deeper himself.
How to make improper code comment become proper one ?
Take a look at sample below and let’s see
As you can see, with the code comment above, user might be able to understand that this query string data will be fetched from Query inside request Url using a method called “ParseQueryString” of class HttpUtility and base on this user may not need to go deeper anymore.
How to make a code comment in multiple condition logic ?
Here is a good sample for that
As you can see,with the code comment above reader can easily understand that we have 3 cases to get resources. One by local Id, one by feide Id and one as default which is null.