4.8 Comments

This section addresses implementation comments. JSDoc is addressed separatelyin ??.

4.8.1 Block comment style

Block comments are indented at the same level as the surrounding code. They maybe in / … / or //-style. For multi-line / … / comments, subsequentlines must start with aligned with the on the previous line, to makecomments obvious with no extra context.

  1. /*
  2.  * This is
  3.  * okay.
  4.  */
  6. // And so
  7. // is this.
  9. /* This is fine, too. */

Comments are not enclosed in boxes drawn with asterisks or other characters.

Do not use JSDoc (/* … /) for implementation comments.

4.8.2 Parameter Name Comments

“Parameter name” comments should be used whenever the value and method name donot sufficiently convey the meaning, and refactoring the method to be clearer isinfeasible .Their preferred format is before the value with =:

  1. someFunction(obviousParam, /* shouldRender= */ true, /* name= */ 'hello');

For consistency with surrounding code you may put them after the value without=:

  1. someFunction(obviousParam, true /* shouldRender */, 'hello' /* name */);