JavaScript Documentation Comments

Question
Should I use comments for documentation purposes? If so, what are some recommended practices?

Answer
It’s recommended that you use documentation comments when needed. This is especially true for public-facing code that others may use. A best practice is to implement the comments using the Java Doc-style. In addition, be sure to provide documentation comments for methods, constructors, and objects with documented methods. See the examples below.

Comments
I recommend using JSDoc as a documentation generator.

Examples

/**
Java Doc-style comments for JavaScript.

@method addBlogPost
@param {String subject} The blog's subject. 
**/
function addBlogPost(subject) {
  click(addPostButton);
  typeText(subjectLine, subject);
  click(saveButton);
}

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s