Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

Protocols - clarify access to parameters

未关闭
  • 哪里不对？
#215 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

评估

难度
3/5
预计耗时
1-2 天
新手友好度
45/100
Issue 类型
文档
描述清晰度
基本清楚
活跃度
停滞
技术栈
clojure
领域
documentation

调研方向

首先在 clojure-site 文档中找到 Protocols and Data Types 指南，并查看其中目前是如何解释协议方法、defrecord 和 extend-protocol 的。以 issue 中的 Clojure 示例作为拟议澄清的参考；当指南清楚说明这些情况下的属性访问和参数命名时，即视为完成。

由索引模型根据 Issue 内容生成。

描述

help wanted

There are various ways to define and access properties defined with protocols and data types which are non-obvious and not explained or clarified in the Protocols or Data Types guides

I propose updating the Protocol guide with this examples:

Names and values when using defrecord directly
(defprotocol DeviceRegistration
  "Protocol to register various IOT devices"
  (register [device])
  (ping [device]))

(defrecord RaspberryPi [device-id location registry-id]
  DeviceRegistration
  (register [_]
    (->RaspberryPi device-id location 789))

  (ping [_]
    (= 789 registry-id)))

register and ping ignore the method parameters. Instead they uses the properties directly from the record.

Sample Usage
(def rasp-pi (map->RaspberryPi {:device-id 123 :location {:x 123.4 :y 432.1}}))
;=> #'practice1.core/rasp-pi

(def registered-pi (register rasp-pi))
;=> #'practice1.core/registered-pi

(println (type registered-pi))
;practice1.core.RaspberryPi

(def pinged? (ping registered-pi))
;=> #'practice1.core/pinged?

(println pinged?)
; true

Note: Diligent readers will have observed that we can only ever register or ping one RaspberryPi using this code. It's good enough for the example but maybe not production quality.

Names and values when using extend-protocol
(defrecord Arduino [device-id location registry-id])

(extend-protocol DeviceRegistration
  Arduino
  (register [device]
    (assoc device :registry-id 890))

  (ping [device]
    (= 890 (:registry-id device))))

register and ping do not have access to the record directly. They access record properties from the method parameter, which is the Arduino record.

register creates a new Arduino record via assoc. In this case it is simpler than creating a new Arduino record using either ->Arduino or map->Arduino functions supplied by defrecord.

Sample Usage
(def arduino (map->Arduino {:device-id 345 :location {:x 432.1 :y 987.6}}))
;=> #'practice1.core/arduino

(def registered-arduino (register arduino))
;=> #'practice1.core/registered-arduino

(println (type registered-arduino))
;practice1.core.Arduino

(def pinged? (ping registered-arduino))
;=> #'practice1.core/pinged?

(println pinged?)
;true
Code in the wild uses this

Most code I see reads more like, ahem, this:

(extend-protocol DeviceRegistration
  Arduino
  (register [this]
    (assoc this :registry-id 890))

  (ping [this]
    (= 890 (:registry-id this))))

In some languages there is a keyword this or self and it has a special meaning. It kind of does in these cases too - even though the symbol itself is not special in Clojure. Rather than use conventionally privileged words, I prefer the more descriptive option.

Obligatory Clojure documentation rant

Following on from the this mini-rant, I am not a fan of x y z and foo and bar as example parameters or method calls.

Documentation comes to life when it is illustrated with simple and easily understood examples rather than abstract characters and meaningless phrases.

I know 'real things' come and go but these guides are not written to see the heat death of the universe. Are they?

主要语言
HTML
星标
259
派生
276
30 天内没有已合并 PR

环境准备

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

clojure/clojure-site 的其他 Issue

查看 clojure/clojure-site 的全部 Issue

相似的 Issue

更多 Documentation Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。