This page contains some coding conventions for the Groovy-Eclipse project. This is still a work in progress. If you feel there are some conventions that are missing from here, please raise a jira issue for it.
We are only trying to coordinate some high level conventions that maintain the quality of the project across releases and when there are multiple developers. For anything that is not specified here, use your common sense. If you think that there is a major issue of concern, send a message to the firstname.lastname@example.org mailing list.
Copying code from Eclipse and JDT
In general, we want to avoid copying code from JDT and Eclipse. Instead, the preferred way to extend or borrow Eclipse functionality is to use sub-classing and reflection. Where this approach is not possible or it is unwieldy, it may be reasonable to copy an entire file. Here are the guidelines for doing this:
- Add the copied file to the jdt_patch source folder in the plugin. (If this doesn't exist yet, then create it.)
- Change the package name by prefixing 'greclipse." to the package. Do not change the type name.
- First line of the file should describe where it comes from (fully qualified name, plugin, etc).
- If there are visibility problems that mean you cannot change the package name, then leave the package as is and suffix the type name with PATCH. This should be a last resort.
- Surround all changes (apart from the package statement and imports) with "// GROOVY start" and "// GROOVY end"
- If suitable, add a textual description of why you are doing what you are doing after "// GROOVY start"
- If you have been really keen include the bugzilla entry raised against JDT related to the change you are making "prNNNNNN"
- Where you are replacing existing code with new code, use this format:
This ensures comparisons and merges are easier because the old code will precisely match what is in the original file. If the old code includes /* */ comments just apply common sense and think what will be easiest to merge again later.
In some cases, you may want to copy code from JDT as a starting point, but you have no intention of keeping the versions synchronized across Eclipse releases. This situation is fine, but you must keep the original EPL license at the top of the file.
Code formatting, templates, and code cleanups
The Groovy-Eclipse plugins use a set of pre-defined code formatting, templates, and code cleanups. They are set in each project. Also, copies of these preferences are included in the org.codehaus.groovy.eclipse.core project. When creating a new project, be sure to use these preferences.
Task tags in code
Do not use TODO tags. Instead use something like FIXADE (where instead of ADE, use your initials). And after the FIXADE tag, you can optionally include a version number that this change should be applied to (eg- // FIXADE (2.1.0) ). You may also want to add the tag as one that is recognized by the JDT compiler. Go to: Preferences -> Java Compiler -> Task Tags and add what you need.
In general, unless there is a good reason not to, errors should be logged to the error log. To do this, in the catch clause, add the following code:
And when in the org.eclipse.jdt.groovy.core project, use this instead (or one of the variants of the method):
The version field of an issue should be the version of Groovy-Eclipse that the issue was raised against. If unknown, choose the most recently released version. If raised against the latest dev build, also choose the most recently released version.
Only assign an issue to yourself if you intend to work on it in the near future.
Mark the issue as "In Progress" once you are starting to write code.