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

Question

{{counted?}} 的 docstring 目前说明：

bq. 如果 coll 实现了常数时间内的 count，则返回 true

这会让用户误以为可以使用此函数来确定调用任何集合的 count 是否是常数时间操作，而实际上它只反映了对象是否实现了 {{clojure.lang.Counted}} 接口。由于 {{count}} 对平台类型有一些特殊处理，因此存在一些常见的常时间操作，例如数组字符串，但仍会从 {{counted?}} 返回 false。

**建议：**

bq. 如果 Clojure 集合 coll 实现了 count 操作为常数时间，则返回 true。请注意，即使计数值可以为宿主类型在常数时间内返回（如数组和字符串），此函数对于宿主类型仍会返回 false。

Answer 1

评论由：gfredericks 提出

附加了 CLJ-1607-p1.patch，这是我关于更好的 docstring 的第一次草稿。

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](https://clojure.atlassian.net/browse/CLJ-1607)（由gf Fredericks报告）