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

Question

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

bq. 如果col集合以常数时间实现计数，返回true

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

*建议：*

bq. 如果Clojure集合col以常数时间实现计数，则返回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

这种措辞怎么样？

如果Clojure集合coll实现了以常数时间计数，则返回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报告）