如果不打算使用 "return callback()" 值，我是否应该将其记录为 return 值？

Question

我有一段代码return没什么用：

/**
 * Close the web server
 *
 * @param {function} callback - Called after web server is stopped
 */
PolyApp.prototype.stop = function(callback) {
  if (!this._listeningServer) {
    if (callback) {
      return callback();
    }

    return;
  }

  this._listeningServer.close(callback);
};

这个函数利用return来控制执行流程。鉴于它 return 没有任何用处，我想避免记录它。这给了我以下好处：

文档更加清晰，因为它记录了使用意图
代码中没有提供任何价值的注释变得不那么混乱
我避免签订 return 我不想维护的合同。

另一方面：

我return正在计算一个没有记录的值

我认为我不应该记录它，因为我不希望人们依赖任何 returning 行为。

你觉得呢？我做的是务实的吗？

Answer 1

您想记录什么由您决定。你必须问自己这个问题："Will I, or other people, ever need to see this documentation to get additional knowledge?"。对于不需要任何特定 return 行为的回调，您不需要记录任何内容。你应该为 stop 指定它会 return 无论回调 returns。否则人们可能会感到困惑。

如果不打算使用 "return callback()" 值，我是否应该将其记录为 return 值？

Should I document a "return callback()" as return value if it is not intended to be used?

jsdoc