为啥 JavaScript 函数文档在函数之外？

Posted 2023-03-15

【中文标题】为啥 JavaScript 函数文档在函数之外？

【英文标题】：Why is JavaScript function documentation outside the function?为什么 JavaScript 函数文档在函数之外？

【发布时间】：2018-12-14 03:41:58

【问题描述】：

在 javascript 中，大多数文档格式似乎都在函数上方放置了一个块：

/**
 * example JavaScript docstring
 */
function myFunction()...

（例如：JSDoc）

然而，在 Python 中，大多数文档格式在函数体内使用文档：

def my_function():
    """ Do amazing things
    """
    (function body here)

（例如：PEP 257）

来自 Python 背景，这似乎是一种更实用的格式，因为：

您不必维护所有 *stars 及其间距 文档生成器更容易通过抓取函数体进行自省 函数签名自然会成为文档的“一部分”，因为它就在那里，您可以在文档之前阅读函数名称，而无需先滚动过去。

为什么约定将文档放在 JavaScript 中的函数之外？我的猜测是它是旧语言的遗留物，但我想要一个比这更令人信服的理由。我希望这有一个有趣的历史或实际原因。启发我！

【参考方案1】：

Python 中的文档字符串是该语言本身的一个特性。我的意思是，Python 本身会在类或函数的顶部检测到一个字符串，并将该字符串存储为 function.__doc__。

所以函数的文档是和函数一起存储的，所以你可以help(function)在解释器中读取。

这就是 Python 中的自省是多么容易。类和函数都是对象，所以你只需访问它们的__doc__ 变量，瞧，你就有了文档字符串。

Javascript 从未决定添加这样的功能，因此文档在解释时不可用，需要通过文档生成器实用程序从源代码文件中提取。这对于为在浏览器中运行而优化的语言来说是有意义的——大多数时候你甚至不想加载文档文本。

即便如此，Javascript 文档框架可以而且应该将文档 cmets 放置在函数内部，而不是外部。这种放置的好处之一是，当我在编辑器中使用代码折叠时，我只会看到函数名称（在这种情况下我不想看到任何文档）。最好只在我将鼠标悬停在我感兴趣的函数上时才能看到文档文本的开头。

我猜框架没有为文档 cmets 选择最佳位置的原因是......他们没有这个想法。您可以将其视为Blub Paradox 的缩影：如果您没有体验过 Python 的优势，那么您就会忘记（甚至否认）它们。这甚至适用于人机工程学——见证大量程序员说他们不喜欢有意义的空格，这些空格摆脱了手动维护的丑陋花括号的代码……每个人都通过缩进解析代码，而不是通过花括号……

顺便说一句，Python 缺少多行 cmets 是不正确的（正如本页其他地方所断言的那样），因为您可以在代码中的任意位置编写多行字符串，而无需将字符串分配给任何变量，并且对于所有意图和目的它看起来像一个评论。此外，Javascript 确实有具体的多行 cmets，但哪些文档框架真正使用了这些 cmets？我的意思是，我们的一个抱怨是必须维护数百个星号......多行 cmets 对 Javascript 所做的非常好，对吧？

【参考方案2】：

JS 中使用的格式来自该语言的 C 背景，因为开箱即用地支持多行 cmets，它使事情变得更容易。

请记住，与其说是技术选择，不如说是审美选择，因此不一定有明确、清晰的解释。

【讨论】：

此外，由于评论标准是每个开发人员都必须花费时间的事情，而且由于风格会影响其可消费性和可维护性，因此有人可能会争辩说，它既是一种技术选择，也是一种审美选择：你的根据您的文档使用和维护的难易程度，团队会更快或更慢。