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 42402f2a351 Clarify override Javadoc guidance (#38820)
42402f2a351 is described below
commit 42402f2a351e4a1edd9ffd16780897f89c64b777
Author: Liang Zhang <[email protected]>
AuthorDate: Sat Jun 6 12:48:58 2026 +0800
Clarify override Javadoc guidance (#38820)
Add AI-agent guidance to avoid duplicating Javadocs on overridden methods
when the parent API, SPI, or interface already carries the public contract.
The rule also documents the exception cases for implementation-specific
behavior and asks reviewers to preserve public contract information when
cleaning redundant override Javadocs.
---
AGENTS.md | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
index 5a289353288..3f012932ae8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,6 +28,11 @@ This guide is written **for AI coding agents only**. Follow
it literally; improv
For simple internal two-path flows, avoid marker interfaces, multi-type
result hierarchies, or extra DTO-style helpers.
Add them only when they define a stable boundary, keep owner classes
readable, or remove meaningful duplicated logic.
- Delete unused code; when changing functionality, remove legacy
compatibility shims.
+ - Do not add or keep Javadocs on methods that only override or implement a
documented parent method.
+ Keep the public contract on the declaring API, SPI, or interface.
+ 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; if a value must be
retained, declare it `final` to satisfy Checkstyle
VariableDeclarationUsageDistance.
- 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.
- Do not add explicit defensive immutable collection copies in
constructors or method return values by default.
