clojure-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clojure Code Review Skill

Clojure代码评审技能

@./../_shared/clojure-style-guide.md @./../_shared/clojure-commands.md

Review guidelines

评审指南

What to flag:

Check compliance with the Metabase Clojure style guide (included above)
If
```
CLOJURE_STYLE_GUIDE.adoc
```
exists in the working directory, also check compliance with the community Clojure style guide
Flag all style guide violations

What NOT to post:

Do not post comments congratulating someone for trivial changes or for following style guidelines
Do not post comments confirming things "look good" or telling them they did something correctly
Only post comments about style violations or potential issues

Example bad code review comments to avoid:

This TODO comment is properly formatted with author and date - nice work!

Good addition of limit 1 to the query - this makes the test more efficient without changing its behavior.

The kondo ignore comment is appropriately placed here

Test name properly ends with -test as required by the style guide.

Special cases:

Do not post comments about missing parentheses (these will be caught by the linter)

需要标记的内容：

检查是否符合Metabase Clojure风格指南（已包含在上方）
如果工作目录中存在
```
CLOJURE_STYLE_GUIDE.adoc
```
，同时检查是否符合社区Clojure风格指南
标记所有风格指南违规情况

请勿发布的内容：

请勿发布对微小变更或遵循风格指南的表扬评论
请勿发布“看起来不错”或确认对方操作正确的评论
仅发布关于风格违规或潜在问题的评论

需避免的错误代码评审评论示例：

这个TODO注释的格式正确，包含了作者和日期 - 做得好！

在查询中添加limit 1很棒 - 这让测试更高效且不改变其行为。

kondo忽略注释的位置很合适

测试名称正确以-test结尾，符合风格指南要求。

特殊情况：

请勿发布关于缺失括号的评论（这些会被检查器捕获）

Quick review checklist

快速评审清单

Use this to scan through changes efficiently:

使用此清单高效扫描代码变更：

Naming

命名

Descriptive names (no
```
tbl
```
,
```
zs'
```
)
Pure functions named as nouns describing their return value
```
kebab-case
```
for all variables and functions
Side-effect functions end with
```
!
```
No namespace-alias repetition in function names

使用描述性名称（避免
```
tbl
```
、
```
zs'
```
这类缩写）
纯函数使用描述返回值的名词命名
所有变量和函数使用
```
kebab-case
```
命名法
有副作用的函数以
```
!
```
结尾
函数名称中不要重复命名空间别名

Documentation

文档

Public vars in
```
src
```
or
```
enterprise/backend/src
```
have useful docstrings
Docstrings use Markdown conventions
References use
```
[[other-var]]
```
not backticks

TODO

comments include author and date:

;; TODO (Name 2025-01-01) -- description

```
src
```
或
```
enterprise/backend/src
```
中的公共变量需包含实用的文档字符串
文档字符串使用Markdown规范
引用使用
```
[[other-var]]
```
而非反引号

TODO

注释需包含作者和日期：

;; TODO (Name 2025-01-01) -- 描述内容

Code Organization

代码组织

Everything
```
^:private
```
unless used elsewhere
No
```
declare
```
when avoidable (public functions near end)
Functions under 20 lines when possible
No blank, non-comment lines within definition forms (except pairwise constructs in
```
let
```
/
```
cond
```
)
Lines ≤ 120 characters

除非在其他地方使用，否则所有内容标记为
```
^:private
```
尽可能避免使用
```
declare
```
（公共函数放在末尾）
函数代码尽可能控制在20行以内
定义形式内不要有空的非注释行（
```
let
```
/
```
cond
```
中的成对结构除外）
每行长度≤120字符

Tests

测试

Separate
```
deftest
```
forms for distinct test cases
Pure tests marked
```
^:parallel
```
Test names end in
```
-test
```
or
```
-test-<number>
```

不同的测试用例使用独立的
```
deftest
```
形式
纯测试标记为
```
^:parallel
```
测试名称以
```
-test
```
或
```
-test-<数字>
```
结尾

Modules

模块

Correct module patterns (OSS:

metabase.<module>.*

, EE:

metabase-enterprise.<module>.*

)

API endpoints in
```
<module>.api
```
namespaces
Public API in
```
<module>.core
```
with Potemkin
No cheating module linters with
```
:clj-kondo/ignore [:metabase/modules]
```

使用正确的模块模式（开源版：
```
metabase.<module>.*
```
，企业版：
```
metabase-enterprise.<module>.*
```
）
API端点放在
```
<module>.api
```
命名空间中
公共API放在
```
<module>.core
```
中并使用Potemkin
不要使用
```
:clj-kondo/ignore [:metabase/modules]
```
规避模块检查器

REST API

Response schemas present (
```
:- <schema>
```
)
Query params use kebab-case, bodies use
```
snake_case
```
Routes use singular nouns (e.g.,
```
/api/dashboard/:id
```
)
```
GET
```
has no side effects (except analytics)
Malli schemas detailed and complete
All new endpoints have tests

存在响应模式（
```
:- <schema>
```
）
查询参数使用kebab-case，请求体使用
```
snake_case
```
路由使用单数名词（例如：
```
/api/dashboard/:id
```
）
```
GET
```
请求无副作用（分析统计除外）
Malli模式详细且完整
所有新端点都有对应的测试

MBQL

No raw MBQL manipulation outside
```
lib
```
,
```
lib-be
```
, or
```
query-processor
```
modules
Uses Lib and MBQL 5, not legacy MBQL

除
```
lib
```
、
```
lib-be
```
或
```
query-processor
```
模块外，不要直接操作原始MBQL
使用Lib和MBQL 5，而非旧版MBQL

Database

数据库

Model and table names are singular nouns
Uses
```
t2/select-one-fn
```
instead of selecting full rows for one column
Logic in Toucan methods, not helper functions

模型和表名使用单数名词
使用
```
t2/select-one-fn
```
替代查询整行来获取单个列的值
逻辑放在Toucan方法中，而非辅助函数

Drivers

驱动

New multimethods documented in

docs/developers-guide/driver-changelog.md

Passes
```
driver
```
argument to other driver methods (no hardcoded driver names)
Minimal logic in
```
read-column-thunk
```

新的多方法需在

docs/developers-guide/driver-changelog.md

中记录

向其他驱动方法传递
```
driver
```
参数（不要硬编码驱动名称）
```
read-column-thunk
```
中的逻辑尽可能精简

Miscellaneous

其他

Example data is bird-themed when possible
Kondo linter suppressions use proper format (not
```
#_:clj-kondo/ignore
```
keyword form)

示例数据尽可能使用鸟类主题
Kondo检查器抑制规则使用正确格式（不要使用
```
#_:clj-kondo/ignore
```
关键字形式）

Pattern matching table

模式匹配对照表

Quick scan for common issues:

Pattern	Issue
`calculate-age` , `get-user`	Pure functions should be nouns: `age` , `user`
`update-db` , `save-model`	Missing `!` for side effects: `update-db!` , `save-model!`
`snake_case_var`	Should use kebab-case
Public var without docstring	Add docstring explaining purpose
`;; TODO fix this`	Missing author/date: `;; TODO (Name 2025-01-01) -- description`
`(defn foo ...)` in namespace used elsewhere	Should be `(defn ^:private foo ...)`
Function > 20 lines	Consider breaking up into smaller functions
`/api/dashboards/:id`	Use singular: `/api/dashboard/:id`
Query params with `snake_case`	Use kebab-case for query params
New API endpoint without tests	Add tests for the endpoint

快速扫描常见问题：

模式	问题说明
`calculate-age` , `get-user`	纯函数应使用描述返回值的名词命名：建议将 `get-user` 改为 `user`
`update-db` , `save-model`	有副作用的函数缺少 `!` ：应改为 `update-db!` , `save-model!`
`snake_case_var`	应使用kebab-case命名法
公共变量无文档字符串	添加说明其用途、输入和输出的文档字符串
`;; TODO fix this`	缺少作者/日期：应改为 `;; TODO (Name 2025-01-01) -- 描述内容`
`(defn foo ...)` 在其他命名空间中使用	应标记为 `(defn ^:private foo ...)`
函数代码超过20行	考虑拆分为更小的函数
`/api/dashboards/:id`	使用单数形式： `/api/dashboard/:id`
查询参数使用 `snake_case`	查询参数应使用kebab-case：将 `user_id` 改为 `user-id`
新API端点无测试	为此端点添加测试

Feedback format examples

反馈格式示例

For style violations:

This pure function should be named as a noun describing its return value. Consider
user
instead of
get-user
.

For missing documentation:

This public var needs a docstring explaining its purpose, inputs, and outputs.

For organization issues:

This function is only used in this namespace, so it should be marked
^:private
.

For API conventions:

Query parameters should use kebab-case. Change
user_id
to
user-id
.

针对风格违规：

此纯函数应使用描述返回值的名词命名。建议将
get-user
改为
user
。

针对缺失文档：

此公共变量需要添加说明其用途、输入和输出的文档字符串。

针对代码组织问题：

此函数仅在当前命名空间中使用，因此应标记为
^:private
。

针对API规范问题：

查询参数应使用kebab-case。请将
user_id
改为
user-id
。