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

Question

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

bq. 如果集合实现 count 是在常数时间内返回 true

这会让用户误以为可以使用此功能来确定对任何集合调用 count 是否是常数时间操作，而实际上它仅反映对象是否实现了 {{clojure.lang.Counted}} 接口。由于 {{count}} 为几种平台类型进行了特殊处理，因此存在如数组（Arrays）和字符串（Strings）此类常量时间操作的情况，但 {{counted?}} 会返回 false。

*建议：*

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

Answer 1

评论者：gfredericks

附上 CLJ-1607-p1.patch，包含我更好的文档字符串的首个草稿。

Answer 2

评论者：gfredericks

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

Answer 3

评论者：alexmiller

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

我相信count处理了除了常数时间内可计数的集合（如sequence）之外的情况，所以不打算与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。存在或不存在的内容都是经过精心挑选的。

我同意您的观点，可能需要更多词汇来充分描述对core中任何一个函数的期望。从Rich对这类问题的回应来看，他可能也会同意这一点，但他更希望这些信息存活在外部参考资料或其他来源之外。并不是说我们不更新文档字符串，因为这也经常发生；我只是认为这个文档字符串可能不会被接受。我已经让Stu再用一双眼睛来看看。

Answer 9

评论者：gfredericks

这是有用的细节，谢谢！

Answer 10

评论者：arrdem

我认为这个文档字符串现在的形式就很好，因为count的文档字符串明确指出“也适用于...”，这暗示了这些内容不会被counted?计算在内。

Answer 11

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