Application Development Tips and Tricks > Coding conventions > Commenting your code

Commenting your code

Always comment code in an application. Comments are the author's opportunity to tell a story about what the code was written to do. Comments should document every decision that was made while building an application. At each point where a choice was made about how to code the application, place a comment describing that choice and why it was made.

When writing code that is a work-around for specific issue, make sure you add a comment that will make the issue clear to future developers who may be looking at the code. This will make it easier for them to address that issue.

Here is an example of a simple comment for a variable:

var clicks = 0; // variable for number of button clicks

Block comments are useful when a comment contains a large amount of text:

/*
Initialize the clicks variable that keeps track of the number of times
the button has been clicked.
*/

Some common methods for indicating specific topics are:

	// :TODO: topic
	Indicates that there is more to do here.
	// :BUG: [bugid] topic
	Shows a known issue here. The comment should also explain the issue and give a bug ID if applicable.
	// :KLUDGE:
	Indicates that the following code is not elegant or does not conform to best practices. This comment alerts others to provide suggestions about how to code it differently next time.
	// :TRICKY:
	Notifies developers that the subsequent code has a lot of interactions. Also advises developers that they should think twice before trying to modify it.