clojure.core/counted? 的文档字符串应该更加具体

Question

{{counted?}} 的文档字符串目前说明

“如果 coll 实现了常量时间的 count，则返回 true”

这可能导致用户认为他们可以用这个函数来确定在对任何集合调用 {{count}} 时是否为常量时间操作，而实际上它只反映对象是否实现了 {{clojure.lang.Counted}} 接口。由于 {{count}} 对一些平台类型进行了特殊处理，因此对于数组或字符串等常见情况，虽然时间是常量，但 {{counted?}} 将返回 false。

**建议：**

“如果 clojure 集合 coll 实现了常量时间的 count，则返回 true。请注意，即使大小可以在常量时间内获取（如数组或字符串），此函数也会为宿主类型返回 false。”

Answer 1

评论者：gfredericks

附上 CLJ-1607-p1.patch，其中包含我改进的文档字符串初稿。

Answer 2

评论者：gfredericks

描述异常的最准确的语言是什么？我在第一个补丁中使用“某些集合”，但也许“原生集合”或“宿主集合”会更有用？

Answer 3

评论者：alexmiller

虽然我理解你的观点，但我觉得“counted?”的意思并不是回答“这个事物是否可以在常量时间内计数”的问题，而是针对参与Clojure集合库的集合，这包括内部集合如PHM、PHS、PV等，也包括使用这些接口标记其能力的外部集合。

我相信count可以处理比仅仅计数的集合（如序列）更多的情况，因此并不打算与counted?对称。

Answer 4

评论者：gfredericks

当然，我并没有建议改变函数的功能，只是修改文档字符串来降低误导性。

Answer 5

评论者：gfredericks

这种措辞怎么样？

如果coll是一个Clojure集合，且实现count操作的时间是常量，则返回true。请注意，对于宿主类型（例如数组和字符串），即使它们的count函数可以以常量时间返回它们的大小，此函数也会返回false。

Answer 6

评论者：alexmiller

我认为这不太可能通过审查，但这只是我的猜测。

Answer 7

评论者：gfredericks

我试图弄清楚这里的分歧在哪里；你是在争论这些观点之一，还是其他观点？

1. 文档字符串不会通过让人们认为它为宿主集合提供有意义的响应而引起混淆。
2. 如果文档字符串让人们感到困惑，这不是我们需要解决的问题。
3. 这是一个我们应该解决的问题，但我提出的更改是一个不好的解决方案。

Answer 8

评论者：alexmiller

通常，文档字符串倾向于简洁和本质，而不是详尽的示例或情况。我怀疑文档字符串表达了Rich想要表达的内容，并且他可能会认为您添加的点在当前文档字符串中是隐含的，因此是不必要的。特别是，“coll”在所有文档字符串中都比较一致地用来指代Clojure集合（或序列）。文档字符串中存在隐含的else，表示counted?对于非Clojure集合的返回值为false。所使用的词语（和未使用的词语）是经过仔细选择的。

我同意您的看法，可能需要更多的词汇来全面描述对此或其他任何核心函数的期望。从我看到Rich对这类事情的回应来看，他也可能会同意这个观点，但他可能更倾向于将这些内容放在文档字符串以外的参考资料或其他来源中。并非我们不更新文档字符串，因为那样的事情经常发生；只是我认为这个文档字符串不会被接受。我还请Stu让我看看第二遍。

Answer 9

评论者：gfredericks

感谢这个有帮助的细节！

Answer 10

评论者：arrdem

我认为这个评论很好，因为count的文档明确指出“也适用于...”，这表示没有包含在counted?计算中。

Answer 11

参考：https://clojure.atlassian.net/browse/CLJ-1607（由gfredericks报告）