对于 `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

Alex，我想你一定是看错了问题报告 —— 问题报告者建议引导使用 assoc! 的返回值，而不是完全避免使用 assoc!。

文档字符串不仅不明确，而且在问题报告者指出的情况下实际上是错误的。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

由于今天早些时候提交了一些更改，因此补丁 CLJ-1385-reword-docstrings-on-transient-update-funct.patch 日期为 2014年4月6日，不再适用于最新的 Clojure 主版本。我怀疑，鉴于它们是文档字符串更改，应该可以轻松更新补丁以干净地应用，但也可能有对主版本提交了文档字符串更改。

Answer 10

评论者：gfredericks

附上一个新的补丁。

Answer 11

评论者：richhickey

我认为它仍然可以更清楚地表达，因为我们要让人们知道原始集合可能受到了影响并返回了，而返回值必须用于随后的调用。我认为来自瞬态页面的一些语言应该包含在这些文档字符串中。

Answer 12

评论者：jafingerhut

是否可以说，在操作完成后，传递给 pop! conj(image: assoc) 等. 的集合的内容是未定义的，只有返回值的内容是定义良好的？

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

Answer 13

评论由：alexmiller 提供

我在处理这个问题。

Answer 14

评论由：alexmiller 提供

未完成，我（仍然）负责这个

Answer 15

参考：[https://clojure.atlassian.net/browse/CLJ-1385](https://clojure.atlassian.net/browse/CLJ-1385)（由 alex+import 呈报）