2024 Clojure 状态调查! 中分享您的想法。

欢迎!请参阅 关于 页面了解此功能的更多信息。

+3
文档
已关闭

《assoc!` 和 `conj!` 的文档字符串都说 "返回 coll.",这可能意味着瞬态编辑是(总是)即时发生的,其中 `coll` 是第一个参数。但实际上并非如此,应始终使用返回的集合。

方法:在 `conj(image:` , `assoc)` 和 `pop!` 的文档字符串中将 "返回 coll." 替换为 "返回一个更新后的集合"。

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

审核人: Alex Miller

关闭并备注: 发布在 Clojure 1.12.0-beta1(更改了 'transient' 文档字符串)

15 个答案

0

由: alexmiller 发布的评论

在修改瞬态集合时,必须使用像 assoc! 这样的函数返回的集合。这里的 ! 表示其破坏性。瞬态页面(https://clojure.org/transients)明确地描述了调用模式:"您必须在下一次调用中捕获和使用返回值。"。

我不同意我们应该引导程序员远离使用像 assoc! 这样的函数 -- 瞬态被用作性能优化,并且在循环中使用 assoc! 或 conj! 通常是最快的版本。然而,我认为使文档字符串更加明确将是有益的。

0

评论由:gfredericks发表

Alex,我认为你一定看错了工单——原始发帖者建议使用assoc!的返回值进行引导,而不是完全避免使用assoc!

文档字符串不仅是不明确的,而且在原始发帖者所指出的特定情况下实际上是错误的。conj!assoc在数组映射转换为哈希映射的点上并不返回{{coll}},并且它们这样做应该是实现细节,我认为就是这样。

0

由: alexmiller 发布的评论

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

{{assoc}}和{{conj}}都明确说明“返回一个新的集合”,而assoc!conj!说“返回coll。”我理解为“返回修改后的集合”,不考虑是否是相同的实例,但我也可以按照你说的那样读。

说“返回更新后的集合。”能传达正确的意思吗?用“集合”代替“coll”可以消除与变量的具体联系,而“更新”更强烈地暗示你应该使用返回值。

0

评论由:pyrtsa发表

@Alex,这个更新听起来对我很有帮助,仅供参考。

0

评论由:gfredericks发表

是的,我认为这更好。感谢Alex。我很乐意为此提交一个补丁,但我猜想这个变更太大,不适合提交补丁?

0

评论由:jafingerhut发表

对于这类变更,补丁就是过去常常用到的方法,如果是文档字符串而不是clojure.org网页上的内容。

0
答者

由: alexmiller 发布的评论

是的,需要补丁。

0
答者

评论由:gfredericks发表

很高兴提了这个问题。

附上的补丁也更新了 `pop!` 的文档字符串,它也存在相同的问题,尽管从这个角度看,它可能不太重要,因为据我所知,`pop!` 总是返回相同的集合(但我不认为这是合同的一部分)。

0
答者

评论由:jafingerhut发表

由于今天早些时候提交了某些更改,补丁 CLJ-1385-reword-docstrings-on-transient-update-funct.patch 已不再适用于最新的 Clojure master,无法干净地应用。由于这是修改文档字符串的更改,因此我怀疑更新补丁以干净地应用应该很简单,但可能已经对 master 提交了文档字符串的更改。

0
答者

评论由:gfredericks发表

附上了一个新的补丁。

0
答者

评论者:richhickey

我认为它仍然可以更清晰,因为我们想让人知道原始的集合可能已经被修改并返回了,并且返回值必须用于后续调用。我认为来自“临时页面”的一些语言应该融入这些文档字符串中。

0
答者

评论由:jafingerhut发表

能否正确地说,在操作完成后,传递到 pop! conj(image: assoc) 等中的集合具有未定义的内容,而只有返回值具有定义的内容?

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

0

由: alexmiller 发布的评论

我正在处理这个问题。

0

由: alexmiller 发布的评论

未完成,并且我(仍然)拥有这个问题

0
参考: https://clojure.atlassian.net/browse/CLJ-1385 (由 alex+import 报告)
...