clojure.core/counted?的docstring应该更具体

Question

当前{{counted?}}的docstring表示

如果col实现count操作是常数的，则返回true

这会让用户以为可以使用这个函数来判断调用任何集合的{{count}}操作是否是常数时间的，但实际上这仅反映对象是否实现了{{clojure.lang.Counted}}接口。因为{{count}}在平台类型上有一些特殊处理，所以有如数组（Arrays）和字符串这样的常见情况，尽管它们是常数时间操作，但{{counted?}}会返回false。

**建议：**

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

Answer 1

评论区：gfredericks

与我第一次修改的docstring一起附上了CLJ-1607-p1.patch。

Answer 2

评论区：gfredericks

描述异常的语言最准确的形式是什么？我第一次提交中使用了“某些集合”，但也许是“本地集合”或“宿主集合”更恰当？

Answer 3

评论由：alexmiller 提出

虽然我理解你的观点，但我认为"counted?"的意图并不是要回答“这个事情在常数时间内是否可计数”的所有可能类型的问题，而是特别针对参与Clojure集合库的集合。这包括PHM、PHS、PV等内部集合，以及其他使用这些接口标记其能力的外部集合。

我认为count可以处理的案例不仅限于常数时间内计数的集合（如序列），所以并不打算与counted?对称。

Answer 4

评论区：gfredericks

当然，我并没有建议改变函数的功能——只是想通过修改文档字符串，降低其产生误导的可能性。

Answer 5

评论区：gfredericks

这种表述如何？

当 Clojure 集合 coll 实现了常数时间内的 count 时，返回 true。注意，对于宿主类型即使 count 函数可以在常数时间内返回它们的大小（例如数组和字符串），此函数仍将返回 false。

Answer 6

评论由：alexmiller 提出

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

Answer 7

评论区：gfredericks

我在试图弄清楚这里的分歧在哪里；你是在争论这些点，还是其他方面的问题？

1. 文档字符串不太可能因为让人们认为它为宿主集合提供了有意义的响应而引起混淆。
2. 如果文档字符串引起人们的混淆，这不是我们必须解决的问题。
3. 这是一个我们应该解决的问题，但我提出的变化是个糟糕的解决方案。

Answer 8

评论由：alexmiller 提出

通常来说，文档字符串更倾向于简洁和本质，而不是详尽的案例或示例。我的怀疑是，文档字符串说出了Rich想要说的话，他可能认为你添加的观点在当前的文档字符串中是暗示的，因此是多余的。具体来说，“coll”在所有文档字符串中很一致地用来表示Clojure集合（或序列）。在文档字符串中存在一个隐式的else，表示当count?遇到非Clojure集合时会返回false。存在（和不存在）的词汇都是经过仔细挑选的。

我同意你的观点，可能需要更多的词汇来完全描述从这个或任何其他核心函数中期待得到的内容。根据我观察Rich对这些事情的回应，他也可能同意这一点，但他可能更愿意将这一点放在文档字符串之外，在参考资料或其他来源中。并不是说我们不会更新文档字符串，因为这确实经常发生；我只是不认为这个会得到接受。我已经让Stu也给我检查一下。

Answer 9

评论区：gfredericks

这个细节很有帮助，谢谢！

Answer 10

评论者：arrdem

我认为这个是好的，因为count的文档字符串明确指出“也适用于...”，这些并不包含在not counted?中。

Answer 11

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