Conversation
|
@iloveeclipse please check, I assume with this we would have avoided the long statements in #2975 |
|
Feel free to submit, I believe it shouldn't hurt. In the concrete example the comment IMO is reasonable, helps me to understand what the test is doing and shouldn't match any of the restrictions added here. |
I disagree about the example. It is not the policy of Eclipse to place tons of Javadoc for small changes in the code. We should avoid this otherwise no one will be able to read it anymore except AI engine. Just ask your AI engine in the a new session what it thinks about the Javadoc generated by your other AI session. |
| - `docs/Naming_Conventions.md` - Package/class naming rules | ||
| - Indent with tabs (4 spaces wide) | ||
| - Encoding: UTF-8 (see `.settings/org.eclipse.core.resources.prefs`) | ||
| - Javadoc is concise: one or two sentences on what the class or method does, without implementation details, issue links or change history, and without `@param`/`@return` tags that only repeat the name |
There was a problem hiding this comment.
It feels to generic to me as a coding standard. e.g. consumer facing API documentation should be held to a different standard than developer/committer facing test documentation.
Also concise (I would more say we want focused Javadoc to what a user needs to know) seems vague here when it comes to documentation - jut look at the javadoc for the JDK itself what is often the documentation - and eclipse platform is not an exception here. We should not expect people look into implementation details to understand the code and I raley see anyone updating the Eclipse Help (what is hard to discover anyways).
So if we really are concerned I would rather have a do/don't list maybe even better at the contribution docs and reference it here like we do a bit above with docs/Naming_Conventions.md
There was a problem hiding this comment.
I change it to "- Javadoc is concise and focused" without dictating the number of sentences so that API can get more documentation if needed.
AI-generated Javadoc, commit messages and PR descriptions tend to be long and repeat what the code or diff already shows. AGENTS.md now asks for short Javadoc that says what a class or method does, and for commit messages and PR descriptions of a few sentences on what changed and why. Assisted-by: multiple AI agents and layers of automated tooling 🤖
36f4540 to
2759482
Compare
3 participants
AI-generated Javadoc, commit messages and PR descriptions tend to be long and repeat what the code or diff already shows, which costs reviewers time. This adds a Coding Standards rule to AGENTS.md asking for concise and focused Javadoc, without fixing a length so that API documentation can still be as detailed as it needs to be. The commit step of the workflow now asks for commit messages and PR descriptions of a few sentences on what changed and why, without plans or bullet-list changelogs.