关于 `conj!` 和 `assoc!` 的文档字符串应建议使用返回值；效果不一定总是在原地生效

Question

关于 `assoc!` 和 `conj!` 的文档字符串说 "返回 coll。"，可能会让人误以为暂时的编辑（总是）在原地发生，其中 "coll" 是第一个参数。然而，情况并非如此，应该总是使用返回的集合。

思路：请在 `conj(image:》、《assoc())》、《pop!` 等文档字符串中，将 "返回 coll。" 改为 "返回一个更新后的集合。"。

补丁：CLJ-1385-reword-docstrings-on-transient-update-funct-2.patch

审核：Alex Miller

Answer 1

评论人：alexmiller

当修改暂时的集合时，需要使用像 assoc! 这样的函数返回的集合。这里的 ! 表示它的破坏性。关于暂时的页面（《https://clojure.org/transients》）描述了调用模式非常明确："你必须捕获并使用下一次调用的返回值。"

我不同意我们应该引导程序员远离使用像 assoc! 这样的函数 -- 暂时主要是用于性能优化，在循环中使用 assoc! 或 conj! 通常是最快的版本。但我确实认为使文档字符串更明确会有所帮助。

Answer 2

评论由：gfredericks提出

亚历克斯，我认为你一定看错了工单——发起人是在建议引导使用assoc!的返回值，而不是完全避免使用assoc!。

而文档字符串并不只是含糊其辞，它实际上在OP指出的具体情况下是错误的。conj!和{{assoc}}在数组映射转换到散列表时并不返回{{coll}}，他们这样做被认为是我所理解的实现细节。

Answer 3

评论人：alexmiller

@Gary - 你是对的，我确实看错了。

{{assoc}}和{{conj}}都明确表示“返回一个新的集合”，而assoc!和conj!表示“返回coll”。我读作“返回修改后的集合”，不考虑是否是同一个实例，但我也可以按照你的方式读。

说“返回更新后的集合”传达了正确的意思吗？用“集合”而不是“coll”摆脱了与变量的具体联系，“更新”更强烈地暗示你应该使用返回值。

Answer 4

评论由：pyrtsa提出

@Alex，就我所知，这个更新听起来是正确的。

Answer 5

评论由：gfredericks提出

是的，我认为这样更好。谢谢Alex。我很乐意为此提交补丁，但我假设这类改变的补丁太重了？

Answer 6

评论由：jafingerhut提出

补丁正是过去此类改变所做的，如果它是一个文档字符串而不是在clojure.org网页上。

Answer 7

评论人：alexmiller

是的，需要补丁。

Answer 8

评论由：gfredericks提出

很高兴提问。

附上的补丁还更新了pop!的文档字符串，它也存在同样的问题，虽然可以说这不太重要，因为据我所知，pop!总是返回相同的集合（但我认为这不属于合约的一部分）。

Answer 9

评论由：jafingerhut提出

由于今天早些时候提交了一些更改，2014年4月6日的补丁CLJ-1385-reword-docstrings-on-transient-update-funct.patch不再适用于最新的Clojure master。我怀疑由于这些更改是文档字符串更改，更新补丁以干净应用应该很简单，但主分支上可能也提交了文档字符串更改。

Answer 10

评论由：gfredericks提出

附上一个新补丁。

Answer 11

点评者：richhickey

我认为还可以更清晰一些，因为我们想让人们知道原始集合可能已被影响并返回，并且返回值必须用于后续调用。我认为transients页面的一些语言应该包含在这些文档字符串中。

Answer 12

评论由：jafingerhut提出

是否可以说，将集合传递给pop! conj(image: assoc)等操作完成后，其内容是未定义的，而只有返回值具有定义明确的内容？

这种强烈的措辞可能引起人们的注意。

Answer 13

评论人：alexmiller

我正在处理这个问题。

Answer 14

评论人：alexmiller

不完整，而且（我仍然）拥有这个。

Answer 15

参考：https://clojure.atlassian.net/browse/CLJ-1385 （由 alex+import 报告）