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 0feebf9a4da Clarify final usage in coding standards (#38907)
0feebf9a4da is described below
commit 0feebf9a4da80a70053a62f444b989c4753c233a
Author: Liang Zhang <[email protected]>
AuthorDate: Wed Jun 24 22:41:09 2026 +0800
Clarify final usage in coding standards (#38907)
Clarify that final on parameters is limited to method parameters,
constructor
parameters, and catch parameters, while local variables, loop variables,
enhanced-for variables, try-with-resources resources, and lambda parameters
should avoid it.
Synchronize the rule across the root coding standard, the English and
Chinese
community docs, and the AI agent handoff guidance.
---
AGENTS.md | 5 ++++-
CODE_OF_CONDUCT.md | 4 +++-
docs/community/content/involved/conduct/code.cn.md | 4 +++-
docs/community/content/involved/conduct/code.en.md | 4 +++-
4 files changed, 13 insertions(+), 4 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 7a81744d75f..9881165cde8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -51,7 +51,9 @@ This guide is written **for AI coding agents only**. Follow
it literally; improv
An overriding method should add Javadocs only when it documents
implementation-specific behavior, stricter preconditions, side effects,
exceptions, compatibility notes,
or semantics not already covered by the parent declaration.
When cleaning redundant override Javadocs, change comments only and
verify no public contract information is lost.
- - Keep variable declarations adjacent to first use to satisfy Checkstyle
VariableDeclarationUsageDistance; do not mark local variables as `final`.
+ - Keep variable declarations adjacent to first use to satisfy Checkstyle
VariableDeclarationUsageDistance; do not mark local variables as `final`,
+ including ordinary local declarations, loop variables, enhanced `for`
variables, and try-with-resources resources.
+ For parameters, use `final` only on method parameters, constructor
parameters and `catch` parameters; leave lambda parameters without `final`
unless surrounding code style or tooling requires it.
- Single-use local variables must be inlined by default; keep a local
variable only when it is reused (for stubbing/verification/assertions) or
materially improves readability.
- For collection declarations in production and test code, use the
least-specific type that expresses the required contract.
Prefer `Collection` for parameters, fields, local variables, and
internal return values when the code only iterates, checks emptiness or size,
@@ -219,6 +221,7 @@ Dangerous operation detected! Operation type: [specific
action] Scope of impact:
do not stop at patching the output artifact. First fix the highest-leverage
root cause in rules, workflow, schema, validators, prompts, regression cases,
or tests so the same class of error is less likely to recur. Update the
report artifact afterward as a consequence of that root-cause fix, unless the
user explicitly requests a one-off result correction only.
- **Execution discipline:** inspect existing code before edits; keep changes
minimal; default to mocks and SPI loaders; keep variable declarations near
first use without marking local variables `final`; inline single-use locals by
default unless reuse/readability justifies retention; delete dead code and
avoid placeholders/TODOs.
+ Before handoff, inspect the Java diff for newly added `final` declarations
and remove any new meaningless local-variable `final`.
Verify code and skills do not contain local machine paths before handoff.
- **CI impact gate:** before handoff, determine affected GitHub Actions from
changed files.
Use `rg` or small `sed` ranges to inspect only matching workflow `paths`,
job names, and execution commands instead of reading every workflow file.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index 9072a5998e9..19c19e99f6e 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -51,7 +51,9 @@ The following code of conduct is based on full compliance
with the [Apache Softw
- Code that needs comments to explain should be extracted into small methods,
using method names for explanation.
- 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.
-- Local variables should not be set as final.
+- 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.
+- 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.
- The order of member variable definitions and parameter passing should remain
consistent across all classes and methods.
diff --git a/docs/community/content/involved/conduct/code.cn.md
b/docs/community/content/involved/conduct/code.cn.md
index 44677c55982..aec8dbe246d 100644
--- a/docs/community/content/involved/conduct/code.cn.md
+++ b/docs/community/content/involved/conduct/code.cn.md
@@ -55,7 +55,9 @@ chapter = true
- 需要注释解释的代码尽量提成小方法，用方法名称解释。
- `equals` 和 `==` 条件表达式中，常量在左，变量在右；大于小于等条件表达式中，变量在左，常量在右。
- 除了构造器入参与全局变量名称相同的赋值语句外，避免使用 `this` 修饰符。
- - 局部变量不应设置为 final。
+ - 对参数使用 `final` 时，仅用于方法入参、构造器入参以及 `catch` 参数。
+ - 局部变量不应设置为 `final`，包括普通局部变量声明、循环变量、增强 `for` 变量和 try-with-resources 资源变量。
+ - Lambda 参数不应标记为 `final`，除非周边代码风格或工具明确要求。
- 除了用于继承的抽象类之外，尽量将类设计为 `final`。
- 嵌套循环尽量提成方法。
- 成员变量定义顺序以及参数传递顺序在各个类和方法中保持一致。
diff --git a/docs/community/content/involved/conduct/code.en.md
b/docs/community/content/involved/conduct/code.en.md
index d7853c0a6d4..271413801e3 100644
--- a/docs/community/content/involved/conduct/code.en.md
+++ b/docs/community/content/involved/conduct/code.en.md
@@ -55,7 +55,9 @@ The following code of conduct is based on full compliance
with the [Apache Softw
- Code that needs comments to explain should be extracted into small methods,
using method names for explanation.
- 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.
-- Local variables should not be set as final.
+- 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.
+- 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.
- The order of member variable definitions and parameter passing should remain
consistent across all classes and methods.
