(iceberg) branch main updated: Docs: Add Javadoc guidance to AGENTS.md (#16764)

[am...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

amogh-jahagirdar pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg.git


The following commit(s) were added to refs/heads/main by this push:
     new 9cc46bb541 Docs: Add Javadoc guidance to AGENTS.md (#16764)
9cc46bb541 is described below

commit 9cc46bb5411d4530a2e10912e7ea2d9c0411e09a
Author: Steven Zhen Wu <st...@gmail.com>
AuthorDate: Wed Jun 10 17:17:56 2026 -0700

    Docs: Add Javadoc guidance to AGENTS.md (#16764)
    
    Capture rdblue's instruction from PR #16689: Javadoc should describe a
    class or method's purpose as if it were defined by an interface, not
    restate or leak implementation details that create churn when the
    implementation changes.
    
    Co-authored-by: Claude Opus 4.7 (1M context) <no...@anthropic.com>
---
 AGENTS.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/AGENTS.md b/AGENTS.md
index 3b49980659..61e9db426e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -90,6 +90,7 @@ The `api/` module has the strongest stability guarantees — breaking changes ar
 - Use `this.` for instance field assignment. `Preconditions` calls first in methods.
 - No `final` on locals. No one-argument-per-line unless necessary.
 - Magic numbers should be named constants. No personal pronouns in comments.
+- Javadoc describes the function or purpose of a class or method, not the implementation. Only describe what callers need to use the component, as though it were defined by an interface. Don't leak implementation details — over-documenting creates churn when the implementation changes.
 - `} else {` on same line. Minimize variable scope. `try-with-resources` for all `AutoCloseable`.
 - Prefer method references over lambdas. Wrap lines at the highest semantic level.
 - Always use imports — never use fully-qualified class names inline.