`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

亚历克斯，我想你可能误解了工单——OP的提议是指导使用`assoc!`的返回值，而不是完全避免使用`assoc!`。

而文档字符串不仅不够明确，而且在OP指出的特定情况下实际上是不正确的。`conj!` 和 `assoc` 在数组映射转为哈希映射时并没有返回 `coll`，而它们在其他方面返回的是实现细节，据我所知。

Answer 3

评论者：alexmiller

@Gary，你是对的，我确实误读了那个。

`assoc` 和 `conj` 都明确指出“返回一个新的集合” whereas `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

我认为还可以更清晰一些，因为我们希望人们知道原始集合可能受到影响并返回，返回值必须用于随后的调用。我认为从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报告）