JavaScript中代码注释的正确方法是什么？

Question

What is the correct way of code comments in Javascript - is the same syntax as in Java? And which tools actually would take advantage of these comments:

  /*
  * Add an element to the group
  * @param {Object}  overlayElement
  * @param {Object} [element2] optional element
  */ 

I found new Resharper 6 (I write JS in VisualStudio 2010) offers the same comments as in C#, but only within the functions body, something like /// <param name="overlayElement"></param> . The JS code comments are not highlighted as such by ReSharper.

What is the best way to go ...?

Answer 1

using // is better than /* */ because then you can use the latter to take out an entire block containing other comments. However, if you want to use an automatic documentation generation tool, you must use comments similar to javaDoc style.

This is an example that would work with YUI DOC (best one) https://yui.github.io/yuidoc/

/**
* This is a description
* @namespace My.Namespace
* @method myMethodName
* @param {String} some string
* @param {Object} some object
* @return {bool} some bool
*/

Answer 2

good practice is to use // instead of /* */

The reason for that is because if you have */ in any part of the comment (assuming you do not intend to end yet), it would end the comment. This happens even if */ is in a string. ie "*/" <--- this would end the comment and would likely to give you a syntax error.

note // ends at a line break so you would need // for every line of comment.

Answer 3

A good example is the Java based commenting still, which is also used with JSDoc. You can find examples here: http://code.google.com/p/jsdoc-toolkit/wiki/FAQ

To add simple onliners as comments, the // is still a good way to comment your code. But for generating documentation, I'd go with the JSDoc syntax. I have used it in the past and it works quite well.