How to Comment Your Javascript Code - JavaScript

Welcome to the first installment in a series that will teach you how to add Javascript functionality to your website and make your HTML pages more interactive.

TABLE OF CONTENTS:

By: James Payne

Poor Best

Rating:

/ 0

August 10, 2012

print this article

SEARCH DEV SHED

TOOLS YOU CAN USE

How to Comment Your Javascript Code

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.

In Javascript, you can comment your code in one of two ways. The first, which I will showcase below, is for single line commenting. Here is an example:

<html>
<body>
<p>This is text displayed in an HTML paragraph tag</p>
<script type="text/javascript">
// Using document.write to print text to the screen
document.write("This text is written to the browser via Javascript");
</script>
</body>
</html>

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:

// Using document.write to print text to the screen

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:

<html>
<body>
<p>This is text displayed in an HTML paragraph tag</p>
<script type="text/javascript">
// Using document.write to print text to the screen
// This code was written by James Payne
// For use on www.devshed.com
// All Rights Reserved
document.write("This text is written to the browser via Javascript");
</script>
</body>
</html>

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:

<html>
<body>
<p>This is text displayed in an HTML paragraph tag</p>
<script type="text/javascript">
/*
Using document.write to print text to the screen
This code was written by James Payne
For use on www.devshed.com
All Rights Reserved
*/
document.write("This text is written to the browser via Javascript");
</script>
</body>
</html>

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:

document.write("This text is written to the browser via Javascript"); // Using document.write to print text to the screen

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.

Summary

Well, that is it for this intro to Javascript tutorial - but never fear, there is much more to come, as we delve into much deeper aspects of Javascript programming and web design fundamentals. Stay tuned and be sure to check out other Javascript tutorials on our site and in our forums as well.

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.