Commenting in JavaScript

You're probably wondering why I chose this topic to write about, but it's funny how people get commenting so wrong while programming. Instead of explaining what or why their code does something, they give you a statement and expect you to figure out their code all on your own. That's wrong, isn't it? I mean, of course you're expected to analyze their code and find out what it does exactly, but when it comes to participating in huge projects, giving you an idea is a necessity - that's called working together.

Good Commenting

After a few times of doing it, you probably assumed that you got commenting down like a boss. And to be honest, I really don't blame you. All it requires is just a short summary of what that line of code (or block of code) does in your program. But it's how you explain it. Some people believe that they need to explain to the extreme just for you to understand what they had written, but that's not really the case. All you need is a nice, short sentence. Especially if someone knows how to program JavaScript. If someone didn't know however, that would be a different story (nosy buzzers).

Take a look at the picture above. The comment is short, clean and responsible for it's purpose. I didn't have to make multiple comments just to explain what my function does, because it honestly doesn't require that much explaining. Just summarizing it turned out to be efficient enough. Tips I advise are:

1. Explain as if you're telling someone your dream, only shorter.
2. Keep it short so that it won't flood the file with your multiple lines of comments.
3. Don't let your comment stretch out in the file so that people have to use the scroll bar to read it. 
4. Beautify your comments if necessary.
5. Always put your comments ABOVE your code. Never underneath it.

This isn't really something I expect for you to stress out over. In fact, it's not even necessary to. Commenting should be fun and powerful at the same time - you just have to do it right. But if you're doing it wrong and nobody understands a single line of your code (especially if it's complex), then you might want to erase what you created or either find another way to explain it correctly. 

Forever Alone with Code

As a short conclusion, don't write a block of code if you can't explain it. Not worth it.

Bad Commenting

Really?!

Sometimes programmers explain what their code does to the point that they're literally teaching you how to program for the first time. That's too far. That's like teaching a forty year old woman how to say a simple English greeting that she probably already knew..
Now, I'm not saying that all of us are smart when it comes to programming, but none of us are stupid either. Especially if we know how to program. hint, hint hint.

Bad comments are usually easy to distinguish from good ones; they don't provide much detail, they're way too long and possibly make absolutely no sense at all. As I mentioned above, summarizing is the key that leads to success. Not all of us are good at writing, but explaining what you did really shouldn't be that hard, unless it's an engine we're talking about - but not even that, because people also make documentations for their engines so that they're understandable, so that's not even a good excuse. Sorry!

Only the fittest will survive.

To avoid such annoyance and to perfect the obvious, practice. And when I mean practice, I mean practice. Every time you write a line of code that seems as if it's going to be complicated for others to understand, attempt to make a comment about it. This helps to see if you actually understood what wrote, so take your time and try giving it a shot.


Hope you guys enjoyed this post! Sorry for not posting earlier - I got caught up with a few things, so it's been a while. But please keep a look out for more posts by me! I'll be updating again shortly. :)