This short article will explain how and why you should use comments in JavaScript.
First up, how to comment.
What is a Comment?
A comment in programing is one or more lines of text that aren’t interpreted as programming instructions. Instead, the computer skips them when executing your code, completely ignoring them. Therefore, comments don’t have to conform to any valid syntax. They’re just text that you read, and the computer doesn’t.
Single-Line Comments in JavaScript
Commenting is easy. How easy? This easy:
// This is a comment
Any line starting with a // (double forward slash) is a comment.
Multi-Line Comments in JavaScript
Leaving comments that span multiple lines is also easy to achieve and uses the following syntax:
/* This is a comment on multiple lines */
Anything between the /* and */ characters will be considered a comment regardless of whether on the same or multiple lines.
You can find out about Javascript’s lexical grammar here.
Why Comment?
Extensive commenting is a good way to document your project and is overall good practice – here are a few reasons why.
Explain Yourself to Others
You might be the only developer on your project now – but what if it gets popular and you have to bring in someone else to help you maintain it and add features?
The reason why you coded something the way you did may not be obvious at first glance, or you might have had to put in a few clever workarounds to deal with a certain issue.
Leave a comment to make sure you aren’t leaving puzzles for your colleagues to solve.
Explain yourself… To Yourself
Ever look back on something you did months or years ago and wonder, “Why the hell did I do it that way?”?
Leave yourself a comment explaining why so you don’t have to rely on your memory.
For Documentation and Debugging
It’s common practice that for every function you have in your application, you should have a comment explaining how it should behave – what values it accepts and what values it should output.
This way, if you’re chasing a bug in your code, you can look at the comment which explains the function and double-check that the function is working as intended.
Leave Old/Buggy Code Behind
You can comment-out code, wrapping code that is no longer required in a comment so that it won’t be executed.
This is useful if you want to leave behind a reminder of how not to do something or if you have a bit of code that might be useful later but isn’t yet required. Put it in a comment for later.
