If you are new to web development, this introduction to commenting in your code is for you. You may have already skimmed through some HTML, CSS, or JavaScript examples and noticed what may appear to be odd lines of code, like the green text here:
These are called comments, and they are essentially helpful notes to explain what exactly that particular bit of CSS is doing. In this example, the comment next to font-size is telling anyone viewing the code that changing the 2em value will resize the hamburger menu icon. The bit next to color lets people know that changing the value of #fff will change the color of the icon.
There are many reasons to include comments, and not all of them are to be helpful hints. Sometimes web developers will do something that’s called commenting out certain lines of code. This is done to keep that bit of code in the document but keep it from actually doing anything.
For example, here a block of HTML is commented out:
The code is kept intact, but it has no effect on the website. Simply deleting the <!—and –> will restore the block and the gif will appear on the screen. This may be done when testing out certain features, or perhaps if there is something that hasn’t quite been made (like a video), but the web developer wants to go ahead and have the code in place.
The article Best practices for writing code comments on Stack Overflow lists nine rules for commenting. Some of the main points are:
Comments should not duplicate the code.
The article explains that sometimes new developers will spell out what every single line of code is doing, which is completely unnecessary and just causes problems.
Good comments do not excuse unclear code.
An example of this would be someone making a variable a single letter, and then adding a comment that explains what the letter stands for. Why not just name the variable something a little more descriptive, like firstname?
Comments should dispel confusion, not cause it.
This is pretty self-explanatory. Always keep it simple. If you feel like you need to write a book to explain a few lines of code, then there is something inherently wrong with your code to begin with.
Provide links to the original source of copied code.
At some point in time, everybody has borrowed some code from an online resource. Do the right thing and give credit where credit is due. There’s usually no need to make it visible on the actual webpage, so comments are a good way to give the author credit for their work.
Add comments when fixing bugs.
This can be very helpful to someone looking over code who might not realize that a particular line is essential to fix some problem they would otherwise not know exists.
I can’t stress enough how important comments can be. Imagine inheriting a website that has tens of thousands of lines of code across several documents. Adding simple things, like comments showing where a certain section starts and ends in HTML markup, or comments in CSS that explain what changing a color will actually effect on the screen can save time.
Unfortunately, there is no universal way to add comments. Commenting in HTML markup is different from CSS or JavaScript. There are ways to add single lines of comments or multiple lines. My next article will explain the differences, but in the meantime check out this list on Wikipedia.
