Assist future developers by writing comments and clean code

by Tony Patton | Oct 16, 2006 6:40:00 PM

Tags: Scripting languages, line comment, Tony Patton, JavaScript, developer, Web Development Zone Newsletter

Takeaway: Tony Patton explains that thoroughly documenting your code either through written documents or code comments helps you and provides future guidance for developers working with the code.

I have preached about documenting code countless times with fellow developers, but I recently unearthed a strange fact: Many developers don't consider JavaScript or HTML coding, so they rarely document such code. Thoroughly documenting your JavaScript code either through written documents or code comments not only helps you, but it also provides future guidance for developers working with the code.

Document your code with comments

Written documentation is good, but I still like to include documentation in the actual code�just in case the written documents cannot be found. Documenting your code is also good practice, and it is easy to do on-the-fly as you are coding. Some languages like Java and C# provide special documentation features.

JavaScript does not include such features, but you can easily include documentation with comments. There are two ways to include a comment in JavaScript:

The /* (start comment) and */ (stop comment) character combinations allow you to include multi-line comments, so everything between the start and stop comment indicators is not executed.
A single line comment is created with two backslash characters (//). Any text after the two backslashes is ignored. These comments may exist on their own line or at the end of a line of JavaScript.

The HTML sample in Listing A includes JavaScript that demonstrates the use of both techniques. It is a simple HTML page that displays a message box when the page is loaded, but it includes plenty of documentation. You may prefer developing the next cool trick, but some of this time can be devoted to documenting your code. After all, great code does not necessarily innovate, but implements in a clean and accessible manner and keeps maintenance easy.

Weekly development tips in your inbox

Keep your developer skills sharp by signing up for TechRepublic's free Web Development Zone newsletter, delivered each Tuesday.

Automatically sign up today!

There is a point where you can include too much information when documenting your code. After all, each and every line of code does not require documentation. Here are a few guidelines for documenting your JavaScript:

Document all functions including their purpose along with description of its parameters and return value (if it exists). My simple example includes such information. I like to include the author and date, but you can choose to include this in the page documentation (since it's probably the same for the entire page), but that is the developer's and organization's preference.
Document any obscure or complex code to help future developers understand what it is doing.
Code changes should include a line detailing the change, as well as who made it and why. This can aid debugging and in tracking down developers.

These guidelines are not stringent and may vary among organizations; the key is to be consistent so all code follows a set approach.

Write clean code

Documenting your code is just one aspect of easing code maintenance. Another way you can help fellow developers is by keeping your code readable through the following additional techniques:

Proper indentation
Self-explanatory variable and method names
Consistent bracket placement for script blocks

While the specifics of code-display within the TechRepublic.com site negates indentation in the sample code in this article, you should indent your code according to developer and/or organization preference. Also, you will notice the variable and function names in the example are rather self-explanatory, so a developer could ascertain code functionality without accompanying comments.

The last item on the list is related to the placement of braces ({ and }) that enclose code blocks. I've worked with organizations that prefer the opening bracket on its own line and others where the first bracket is on the end of the first line of code in the block. The sample code uses the former approach, but the function could easily use the other technique as demonstrated by the code in Listing B.

HTML comments

In addition to JavaScript comments, you can include comments or documentation in HTML with HTML formatted comments. HTML comments use the following formatting:

<!-- This is an HTML comment -->

The sample code includes an HTML comment at the top of the page. Comment placement depends upon the project, but they can easily be used to omit portions of the page from loading/execution to assist with debugging.

Helping others

Developing readable code is a continual process that you should follow on a daily basis. After all, documentation is abhorred by most developers, so going back and documenting code after a project is complete is not on anybody's wish list. You can include comments and consistently format your code to assist future developers charged with maintenance or changes.