How To Write Comments

Comments, while being the most underrated part of any program, can play a significant role in how the development process goes. Although the comments are ignored by the compiler or the interpreter, there is no reason for you, as a developer to ignore writing them.

However, you need to write comments doesn't mean you will put a single comment in the whole code or just write a comment in each line. You should follow some good practices to help your fellow developers or the future you to maintain the code better.

1. Write meaningful names, not comments

Follow good naming conventions for functions, variables, objects etc. You don't need to write a comment to mention what kind of value variable stores.

Instead of doing this

function Funtion1(r) {
    // this function returns the area of a circle
    // r is the radius of the circle
    return 3.1416 * r * r;   
}

You can done this

function CircleArea(radius) {
    return Math.Pi * Math.Pow(radius, 2)
}

As you can see, a good naming practice saved 2 lines of comment.

2. Keep it simple, keep it short

At the end of the day, the sole purpose of a comment is to make the code more readable, not to confuse the developer trying to contribute. Keep it as simple as possible. Try focusing on keywords rather than trying to fix grammatical errors. After all, you are writing code, not a novel.

function SyntaxHighlighter(code) {
    // this function first takes the code as input then highlights the keywords in the code by wraping with <span>. After that it returns it.
    ...
}

function SyntaxHighlighter(code) {
    // returns the syntax highlighted code
}

It wasn't necessary to put a comment in the second code at all as the function name describes the purpose pretty well, but you got the point. 😋

Also, always remember, You are writing comments, not documenting your code. Yes, some of you might argue that commenting is somewhat like documenting code. Yes, I agree too. But this is just a small part of a bigger picture. So for now, just don't.

3. Do NOT add your biography

I have seen enough codes where people go insane and add up as much information as they can in the comment thinking that if other people copy paste their codes, their name will still be in the comments. 🤦‍♂️

I think they don't know there exists a button in the keyboard called Backspace

/* 
Author Name: ABCD WXYZ
Date created: 1/2/2011

Language: Javascript, HTML, CSS
Code Editor: Visual Studio Code

Eye Color: Green
Favorite Color: Blue
Favorite Car: Ford Mustang

Father's Name: ASDFGH
Mother's Name: QWERTY
*/

Why?! Just why?!

4. Don't comment on what bugs the code has

Commonly, you know a specific part of the code is causing some error but you don't have the fix. So, you just commented out that a particular part of the code doesn't work.

function MyFunction(something) {
    ... // This code doesn't work because that code does
}

There is nothing wrong with putting a comment like this. However, I suggest keeping notes of bugs(use the "issues" if you are using Github) as it will help you in the long run if you face the same error again.

5. Avoid zombie codes 🧟‍♂️

But what is a zombie code? 🤨

Well, I don't even know if "zombie code" is an actual term in programming. I just came up with it while writing this blog. Here is an example.

// function CircleArea(radius) {
//     return Math.Pi * Math.Pow(radius, 2)
// }

Makes sense? As you can see, this is a functional code, but disabled. As I mentioned earlier, if you are using some kind of version control system, you don't need to comment out part of a code if you think you don't need it now, but it might be useful later. Just delete it and let the version control system handle the rest.

Well, yeah, this is what I had to say today. Let me know what practices you follow when writing comments.

I wrote the whole thing while attending an online class as I became bored. Forgive me if you see something wrong in here 😋