This is an automated email from the ASF dual-hosted git repository.
terrymanu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git
The following commit(s) were added to refs/heads/master by this push:
new aa503d957ea Clarify coding standard requirements (#39697)
aa503d957ea is described below
commit aa503d957ea7900a277ebce3905ad29241500518
Author: Liang Zhang <[email protected]>
AuthorDate: Wed Sep 2 18:24:10 2026 +0800
Clarify coding standard requirements (#39697)
---
CODE_OF_CONDUCT.md | 12 ++++++------
docs/community/content/involved/conduct/code.cn.md | 12 ++++++------
docs/community/content/involved/conduct/code.en.md | 12 ++++++------
src/resources/checkstyle.xml | 6 +++---
4 files changed, 21 insertions(+), 21 deletions(-)
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index bbb95f7405e..cc2b6c9c3c6 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -18,7 +18,7 @@ The following code of conduct is based on full compliance
with the [Apache Softw
- Ensure all steps in the build process complete successfully, including:
Apache license header check, Checkstyle check, compilation, unit tests, etc.
Build process command: `./mvnw clean install -B -T1C -Pcheck`.
- Unify code style through Spotless, execute `./mvnw spotless:apply -Pcheck`
to format code.
- Ensure coverage is not lower than the master branch, except for simple
`getter /setter` methods, unit tests need full coverage.
-- Try to refine design with fine-grained splitting; achieve small
modifications with multiple commits, but ensure the completeness of each commit.
+- Keep each commit small, complete, and independently verifiable. Split a
change into multiple commits when it contains independent objectives.
- If you use IDEA, you can import `src/resources/idea/code-style.xml` to
maintain code style consistency.
- If you use IDEA, you can import `src/resources/idea/inspections.xml` to
detect potential code issues.
@@ -47,14 +47,14 @@ The following code of conduct is based on full compliance
with the [Apache Softw
- Method parameter names are forbidden from using `result`, `each`, `entry`.
- Utility class names should be named `xxUtils`.
- Configuration files use `Spinal Case` naming (a special `Snake Case` that
uses `-` to separate words).
-- Code that needs comments to explain should be extracted into small methods,
using method names for explanation.
+- Extract code that requires explanatory comments into small methods, and use
method names to express the intent.
- In `equals` and `==` conditional expressions, constants on the left,
variables on the right; in conditional expressions like greater than or less
than, variables on the left, constants on the right.
- Avoid using `this` modifier except for assignment statements where
constructor parameters have the same name as global variables.
- For parameters, use `final` only on method parameters, constructor
parameters and `catch` parameters.
- Local variables should not be set as `final`, including ordinary local
declarations, loop variables, enhanced `for` variables and try-with-resources
resources, unless required by Checkstyle.
-- Lambda parameters should not be marked as `final` unless required by
surrounding code style or tooling.
-- Try to design classes as `final` except for abstract classes used for
inheritance.
-- Nested loops should be extracted into methods.
+- Lambda parameters should not be marked as `final`.
+- Declare every class `final` unless it is an abstract class intended for
inheritance.
+- Extract nested loops into separate methods.
- The order of member variable definitions and parameter passing should remain
consistent across all classes and methods.
- Prefer guard clauses.
- Access control for classes and methods should be minimal.
@@ -101,7 +101,7 @@ The following code of conduct is based on full compliance
with the [Apache Softw
- When a production method is covered by only one test case, name that test
method `assert<MethodName>` without extra suffixes, and prefer isolating one
public production method per dedicated test method; when practical, keep test
method ordering aligned with the corresponding production methods.
- For parameterized tests, provide display names via parameters and use
`"{0}"` as the display-name template.
- Keep test names concise and scenario-focused; avoid `ReturnsXXX` and wording
that restates the expected result instead of naming the scenario.
-- Each test case needs precise assertions, try not to use `not`,
`containsString` assertions.
+- Assertions must directly express the tested contract. Use `not` or
`containsString` only when the contract requires inequality or substring
matching; do not use them when an exact value or a more specific matcher is
available.
- Use JUnit 5 and Mockito. Keep environment preparation, test action, and
assertions distinct; reset static state between scenarios and reuse existing
swappers or helpers for complex configuration.
- Default to direct Mockito mocks. Use a private helper only for repeated
local setup and a standalone fixture only for a stable external or packaged
test boundary. Give fixtures the narrowest practical visibility, keep them in
the nearest owning test package or module, and do not create cross-module test
APIs for convenience. Delete or inline thin mock wrappers.
- Data assertion standards should follow:
diff --git a/docs/community/content/involved/conduct/code.cn.md
b/docs/community/content/involved/conduct/code.cn.md
index efaeb1e8517..588c2afa31b 100644
--- a/docs/community/content/involved/conduct/code.cn.md
+++ b/docs/community/content/involved/conduct/code.cn.md
@@ -22,7 +22,7 @@ chapter = true
- 确保构建流程中的各个步骤都成功完成，包括：Apache 协议文件头检查、Checkstyle 检查、编译、单元测试等。构建流程启动命令：`./mvnw
clean install -B -T1C -Pcheck`。
- 通过 Spotless 统一代码风格，执行 `./mvnw spotless:apply -Pcheck` 格式化代码。
- 确保覆盖率不低于 master 分支，除去简单的 `getter /setter` 方法，单元测试需全覆盖。
- - 应尽量将设计精细化拆分；做到小幅度修改，多次数提交，但应保证提交的完整性。
+ - 每个提交应保持小型、完整且可独立验证。 一个改动包含多个独立目标时，应拆分为多个提交。
- 如果您使用 IDEA，可导入 `src/resources/idea/code-style.xml`，用于保持代码风格一致性。
- 如果您使用 IDEA，可导入 `src/resources/idea/inspections.xml`，用于检测代码潜在问题。
@@ -51,14 +51,14 @@ chapter = true
- 方法入参名禁止使用 `result`、`each`、`entry`。
- 工具类名称命名为 `xxUtils`。
- 配置文件使用 `Spinal Case` 命名（一种使用 `-` 分割单词的特殊 `Snake Case`）。
- - 需要注释解释的代码尽量提成小方法，用方法名称解释。
+ - 需要注释解释的代码应提取为小方法，并通过方法名称表达意图。
- `equals` 和 `==` 条件表达式中，常量在左，变量在右；大于小于等条件表达式中，变量在左，常量在右。
- 除了构造器入参与全局变量名称相同的赋值语句外，避免使用 `this` 修饰符。
- 对参数使用 `final` 时，仅用于方法入参、构造器入参以及 `catch` 参数。
- 局部变量不应设置为 `final`，包括普通局部变量声明、循环变量、增强 `for` 变量和 try-with-resources
资源变量，Checkstyle 明确要求的情况除外。
- - Lambda 参数不应标记为 `final`，除非周边代码风格或工具明确要求。
- - 除了用于继承的抽象类之外，尽量将类设计为 `final`。
- - 嵌套循环尽量提成方法。
+ - Lambda 参数不应标记为 `final`。
+ - 除用于继承的抽象类外，所有类都应声明为 `final`。
+ - 嵌套循环应提取为独立方法。
- 成员变量定义顺序以及参数传递顺序在各个类和方法中保持一致。
- 优先使用卫语句。
- 类和方法的访问权限控制为最小。
@@ -106,7 +106,7 @@ chapter = true
- 每个公有方法使用一个独立的测试方法，测试方法顺序在可行时与生产方法保持一致。
- 参数化测试需通过参数提供显示名，并使用 `"{0}"` 作为展示名模板。
- 测试名称应简洁并聚焦场景；避免使用 `ReturnsXXX`，也不要使用仅复述预期结果而未说明场景的措辞。
- - 每个测试用例需精确断言，尽量不使用 `not`、`containsString` 断言。
+ - 断言必须直接表达被测契约。 仅当被测契约是不相等或包含指定子串时，才可使用 `not` 或
`containsString`；可断言完整值或使用更具体的 matcher 时，不得使用这两个 matcher。
- 使用 JUnit 5 和 Mockito。 明确区分环境准备、测试执行和断言；不同场景之间应重置静态状态，并复用现有的 swapper
或辅助工具处理复杂配置。
- 默认直接使用 Mockito mock。 仅对重复的局部准备使用私有辅助方法，仅对稳定的外部测试边界或打包测试边界使用独立测试夹具。
测试夹具应采用实际可行的最小可见性，并放在最近的所属测试包或模块中；不要为了方便而创建跨模块测试 API。 删除或内联内容单薄的 mock 包装器。
- 数据断言规范应遵循：
diff --git a/docs/community/content/involved/conduct/code.en.md
b/docs/community/content/involved/conduct/code.en.md
index ec04cc37e0a..5644db87076 100644
--- a/docs/community/content/involved/conduct/code.en.md
+++ b/docs/community/content/involved/conduct/code.en.md
@@ -22,7 +22,7 @@ The following code of conduct is based on full compliance
with the [Apache Softw
- Ensure all steps in the build process complete successfully, including:
Apache license header check, Checkstyle check, compilation, unit tests, etc.
Build process command: `./mvnw clean install -B -T1C -Pcheck`.
- Unify code style through Spotless, execute `./mvnw spotless:apply -Pcheck`
to format code.
- Ensure coverage is not lower than the master branch, except for simple
`getter /setter` methods, unit tests need full coverage.
-- Try to refine design with fine-grained splitting; achieve small
modifications with multiple commits, but ensure the completeness of each commit.
+- Keep each commit small, complete, and independently verifiable. Split a
change into multiple commits when it contains independent objectives.
- If you use IDEA, you can import `src/resources/idea/code-style.xml` to
maintain code style consistency.
- If you use IDEA, you can import `src/resources/idea/inspections.xml` to
detect potential code issues.
@@ -51,14 +51,14 @@ The following code of conduct is based on full compliance
with the [Apache Softw
- Method parameter names are forbidden from using `result`, `each`,
`entry`.
- Utility class names should be named `xxUtils`.
- Configuration files use `Spinal Case` naming (a special `Snake Case`
that uses `-` to separate words).
-- Code that needs comments to explain should be extracted into small methods,
using method names for explanation.
+- Extract code that requires explanatory comments into small methods, and use
method names to express the intent.
- In `equals` and `==` conditional expressions, constants on the left,
variables on the right; in conditional expressions like greater than or less
than, variables on the left, constants on the right.
- Avoid using `this` modifier except for assignment statements where
constructor parameters have the same name as global variables.
- For parameters, use `final` only on method parameters, constructor
parameters and `catch` parameters.
- Local variables should not be set as `final`, including ordinary local
declarations, loop variables, enhanced `for` variables and try-with-resources
resources, unless required by Checkstyle.
-- Lambda parameters should not be marked as `final` unless required by
surrounding code style or tooling.
-- Try to design classes as `final` except for abstract classes used for
inheritance.
-- Nested loops should be extracted into methods.
+- Lambda parameters should not be marked as `final`.
+- Declare every class `final` unless it is an abstract class intended for
inheritance.
+- Extract nested loops into separate methods.
- The order of member variable definitions and parameter passing should remain
consistent across all classes and methods.
- Prefer guard clauses.
- Access control for classes and methods should be minimal.
@@ -106,7 +106,7 @@ The following code of conduct is based on full compliance
with the [Apache Softw
- When a production method is covered by only one test case, name that test
method `assert<MethodName>` without extra suffixes, and prefer isolating one
public production method per dedicated test method; when practical, keep test
method ordering aligned with the corresponding production methods.
- For parameterized tests, provide display names via parameters and use
`"{0}"` as the display-name template.
- Keep test names concise and scenario-focused; avoid `ReturnsXXX` and wording
that restates the expected result instead of naming the scenario.
-- Each test case needs precise assertions, try not to use `not`,
`containsString` assertions.
+- Assertions must directly express the tested contract. Use `not` or
`containsString` only when the contract requires inequality or substring
matching; do not use them when an exact value or a more specific matcher is
available.
- Use JUnit 5 and Mockito. Keep environment preparation, test action, and
assertions distinct; reset static state between scenarios and reuse existing
swappers or helpers for complex configuration.
- Default to direct Mockito mocks. Use a private helper only for repeated
local setup and a standalone fixture only for a stable external or packaged
test boundary. Give fixtures the narrowest practical visibility, keep them in
the nearest owning test package or module, and do not create cross-module test
APIs for convenience. Delete or inline thin mock wrappers.
- Data assertion standards should follow:
diff --git a/src/resources/checkstyle.xml b/src/resources/checkstyle.xml
index 245efbfbaf4..c15268e7144 100644
--- a/src/resources/checkstyle.xml
+++ b/src/resources/checkstyle.xml
@@ -168,17 +168,17 @@
<!-- Imports -->
<module name="AvoidStarImport" />
<module name="AvoidStaticImport">
- <property name="excludes"
value="org.junit.jupiter.api.Assertions.assertTrue,org.junit.jupiter.api.Assertions.assertFalse,org.junit.jupiter.api.Assertions.assertNull,org.junit.jupiter.api.Assertions.assertNotNull,org.junit.jupiter.api.Assertions.assertThrows,org.junit.jupiter.api.Assertions.assertDoesNotThrow,org.junit.jupiter.api.Assertions.assertTimeout,org.junit.jupiter.api.Assertions.assertTimeoutPreemptively,org.junit.jupiter.api.Assertions.fail,org.hamcrest.Matchers.arr
[...]
+ <property name="excludes"
value="org.junit.jupiter.api.Assertions.assertTrue,org.junit.jupiter.api.Assertions.assertFalse,org.junit.jupiter.api.Assertions.assertNull,org.junit.jupiter.api.Assertions.assertNotNull,org.junit.jupiter.api.Assertions.assertThrows,org.junit.jupiter.api.Assertions.assertDoesNotThrow,org.junit.jupiter.api.Assertions.assertTimeout,org.junit.jupiter.api.Assertions.assertTimeoutPreemptively,org.junit.jupiter.api.Assertions.fail,org.junit.jupiter.api.Ass
[...]
</module>
<module name="RegexpSinglelineJava">
- <property name="format"
value="^(?!\s*import\s+static\s+).*\b(Mockito|ArgumentMatchers|Assertions|CoreMatchers|Matchers|MatcherAssert|ShardingSphereArgumentVerifyMatchers|ShardingSphereAssertionMatchers)\s*(\.|::)"
/>
+ <property name="format"
value="^(?!\s*import\s+static\s+).*\b(Mockito|ArgumentMatchers|Assertions|Assumptions|CoreMatchers|Matchers|MatcherAssert|ShardingSphereArgumentVerifyMatchers|ShardingSphereAssertionMatchers)\s*(\.|::)"
/>
<property name="ignoreComments" value="true" />
<property name="message" value="Use an allowed static import
instead of a qualified static member call." />
</module>
<module name="IllegalImport">
<property name="regexp" value="true" />
<property name="illegalPkgs" value="sun,.*[.]shaded" />
- <property name="illegalClasses"
value=".*[.]StringUtils([.].*)?,.*[.]CollectionUtils([.].*)?,org[.]junit[.]jupiter[.]api[.]Assertions,org[.]hamcrest[.](CoreMatchers|MatcherAssert|Matchers),org[.]mockito[.](ArgumentMatchers|Mockito),org[.]apache[.]shardingsphere[.]test[.]infra[.]framework[.]matcher[.](ShardingSphereArgumentVerifyMatchers|ShardingSphereAssertionMatchers)"
/>
+ <property name="illegalClasses"
value=".*[.]StringUtils([.].*)?,.*[.]CollectionUtils([.].*)?,org[.]junit[.]jupiter[.]api[.](Assertions|Assumptions),org[.]hamcrest[.](CoreMatchers|MatcherAssert|Matchers),org[.]mockito[.](ArgumentMatchers|Mockito),org[.]apache[.]shardingsphere[.]test[.]infra[.]framework[.]matcher[.](ShardingSphereArgumentVerifyMatchers|ShardingSphereAssertionMatchers)"
/>
</module>
<module name="RedundantImport" />
<module name="UnusedImports" />
