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

Question

Both the docstrings of assoc! and conj! say "Returns coll."，可能表示瞬时常量编辑（总是）是在原地进行的，其中 coll 是第一个参数。然而，情况并非如此，返回的集合始终应该使用。

方法：将 conj(image:，pop!) 和 assoc 的文档字符串中的 "Returns 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! 的返回值，而不是完全避免使用。

而且，文档字符串并非仅仅是模糊不清，实际上在 OP 指出的特定情况下，它实际上是不正确的。《conj!》和 {{assoc}} 在 array-maps 转换为 hash-maps 的点并不返回 {{coll}}，它们在其他方面的行为应该是作为实现细节，据我所知。

Answer 3

评论者：alexmiller

@Gary，你说得对，我确实误解了。

{{assoc}} 和 {{conj}} 明确表示“返回一个新集合”，而 assoc! 和 conj! 表示“返回 coll。”我理解为“返回修改后的集合”，无论它是否是相同的实例，但我也可以理解你的方式。

说“返回更新后的集合。”是否传达了正确的想法？用“collection”代替“coll”消除了具体与变量的联系，“updated”更强烈地暗示你应该使用返回值。

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 便不再适用于最新的 Clojure master，因为它不再干净匹配。我相信，鉴于这些是关于文档字符串的更改，更新补丁以干净匹配应该很简单，但也可能有对主分支提交的文档字符串更改。

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（由 alex+import 报告）