实现注释不要使用 JSDoc (/** … */)？

【问题标题】：Do not use JSDoc (/** … */) for implementation comments?实现注释不要使用 JSDoc (/** … */)？
【发布时间】：2020-12-30 12:46:40
【问题描述】：

我通过 https://google.github.io/styleguide/jsguide.html#formatting-comments 了解 Google 为其开发人员设置的样式指南。

Google 接受以下样式：

 /*
  * This is
  * okay.
 */

// And so
// is this.

/* This is fine, too. */

但有趣的是，谷歌提到了Do not use JSDoc (/** … */) for implementation comments.

我在过去的项目中一直使用 JSDOC 样式。

知道为什么不推荐吗？

【问题讨论】：

标签： comments jsdoc

【解决方案1】：

Google 风格指南Terminology Notes

术语注释总是指实现 cmets。我们不使用短语文档 cmets，而不是使用常用术语用于人类可读文本和机器可读注释的“JSDoc” 在 /** ... */ 内。

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

【讨论】：