manuzhang commented on code in PR #16998: URL: https://github.com/apache/iceberg/pull/16998#discussion_r3489359090
########## AGENTS.md: ########## @@ -89,8 +89,9 @@ The `api/` module has the strongest stability guarantees — breaking changes ar - 2 spaces indent, 4 spaces continuation. Empty newline after control flow blocks. - 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. +- Magic numbers should be named constants. No personal pronouns in comments. Comments should explain non-obvious intent or constraints; don't restate what the code already says. +- Javadoc describes the function or purpose of a class or method, not the implementation. For public APIs, keep it brief and describe only what callers need to use the component, as though it were defined by an interface. Don't leak implementation details. +- Comments and Javadocs should describe the current behavior or contract, not how it changed over time. Review Comment: I like this one. Sometimes I wish it can forget quickly. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
