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

user_7188099 0
Viewed 224

I was going through https://google.github.io/styleguide/jsguide.html#formatting-comments to understand the style guide Google is setting for their developers.

Google accepts the following styles:

 /*
  * This is
  * okay.
 */

// And so
// is this.

/* This is fine, too. */

But interestingly, Google mentions Do not use JSDoc (/** … */) for implementation comments.

I have been using JSDOC styling for my past projects.

Any idea why is it not recommended?

jsdoc comments
1 Answers

The Google Style Guide Terminology Notes

The term comment always refers to implementation comments. We do not use the phrase documentation comments, instead using the common term “JSDoc” for both human-readable text and machine-readable annotations within /** … */.

/**
 * Use JSDoc for documentation comments
 * @param {type} param description
 */
function someFunction(param) {
  // Do not use JSDoc for implementation comments
  const alias = goog.require('my.long.name.alias');
  // ...
}

  [1]: https://google.github.io/styleguide/jsguide.html#terminology-notes

user_109414480
Related