时间戳

首页 > 解决方案 > 为什么 JavaScript 函数文档在函数之外？

javascript - 为什么 JavaScript 函数文档在函数之外？

问题描述

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

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

（例如：JSDoc）

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

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

（例如：PEP 257）

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

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

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

标签： javascriptdocumentationjsdocjsdoc3

解决方案

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

因此函数的文档与函数一起存储，因此您可以help(function)在解释器中阅读它。

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

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

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

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

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

推荐阅读