What is the correct way of code comments in 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 ...?

Aarhus

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
*/

Dismantle

So it is similar to javadoc, good to know. Thanks, to all who have helped. – Aarhus

Your code editor should allow you to mark the text and take it out with // in each line (e.g. Ctrl + /). It will comment out everything no matter what was there. – Ours

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. i.e. "*/" <--- 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.

Pollywog

Note: Ctrl-K, Ctrl-C and Ctrl-K, Ctrl-U are handy shortcuts for commenting and uncommenting code. – Purtenance

I disagree and prefer /* */ always.. minifiers.. and many reasons it always comes in handy. – Jehol

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.

Baronet

Answer 4

Comments in JavaScript are divided into two types: Single line comments or Multi-line comments:

the first is Single line comments start with // Example : let a = 25; // Declare x, give it the value of 25 var b= a -7 2; // Declare y, give it the value of a -7

the secondly is Multi-line comments start with /* Example: /* The code */

Kabob

JFYI: The question (older than 10 years) was about the style to generate automatic documentation as in javadoc etc. Not about comments in general. – Aarhus

Your answer could be improved with additional supporting information. Please edit to add further details, such as citations or documentation, so that others can confirm that your answer is correct. You can find more information on how to write good answers in the help center. – Jordaens