Before we get any further, I think it is important that we delve into a topic that is often covered, but usually ignored by programmers, and that subject is (drumroll) commenting. In my years in the tech world, I've seen programming from many angles: as a writer, an editor, a programmer, quality assurance and testing, actual programming, and project management. It is amazing the amount of times I have had to look over someone's code, only to find that there isn't a single piece of documentation or commenting in the entire program. And since every programmer programs differently, it always turns into a hassle, if not a full-blown nightmare.
For new programmers, commenting means that you describe what a line or several lines of code are intended for, so that you can remember several months later (or another programmer several years later) what you intended that section of code to do. I am not saying a programmer cannot figure it out without comments, but it makes the job a hell of a later easier. It is a common courtesy at the very least and sound programming practice. Do it.
The above code will display the same exact result to the user as our first program. However, when a programmer looks at the code, he will see your comment:
And instantly know what the code following it is supposed to achieve.
So why doesn't the browser do anything with this text? When it sees "//", it ignores everything else on that line and skips to the next line of code.
Commenting on Multiple Lines or Multi-Line Commenting
Sometimes you need more than one line of comments. Maybe it is a complicated section of code or maybe you want your comments to stand out more. There are two ways you can do this. For starters, you can use the method above:
In this instance, I used multiple line comments to state who the author of the code is, what it will be used for, and where it will be published. Using "//" is not always the best method for multi-line commenting however. The standard way is by using this method:
Here, we use the opening multi-line comment "/*", then place all of our comments in-between the opener and the closer - "*/". Anything nestled between is considered a comment and is ignored by the browser.
Other Things to Note About Commenting
You can also put the comment code for a single line at the end of your code as well, like this:
There is really no difference, just a matter of taste.
And finally, commenting isn't always about leaving notes for yourself or others. Sometimes, you may update a page and no longer need the program you wrote, but want to save it just in case you need it in the future, or maybe your page is screwing up and you want to try to debug (check for errors). In that case, you can comment out what you think might be causing the issue. If the page works when you comment out the suspect code, then you know where the problem lies; if not, you know you need to look elsewhere.
Till next time!
About the Author
James Payne is Editor-in-Chief of the Developer Shed Network of sites and has written articles on virtually every technology topic known to man and alien alike. His first book, Beginning Python: Using Python 2.6 and Python 3.1, was recently published by Wiley Books. In addition, he is the publisher of the Science Fiction and Fantasy magazine, Garbled Transmissions, located at www.garbledtransmission.com.
blog comments powered by Disqus