Eclipse Platform/Core Coding Conventions
Here are some of the Coding Conventions that we use as a team.
Common code makes it easier for everyone to read and understand.
Code Formatter:
- set line length to be something large (like 800)
- turn off formatting for comments
- use the core formatting settings found here
Organize imports:
- number of imports needed for *: 3
- remove all entries in list so we don't use the grouping feature
- its all about space...extra blank lines make it hard to read code when
you have a small editor window
Copyright:
- make sure the code has the correct copyright.
- if the code was written in 2003, don't have 2000,2003 in the copyright
- the copyright can be found on the Eclipse
Project Charter page.
Code Comments:
- comments are a good thing.
- comment all "unobvious" things (e.g. don't comment setters/getters)
The art of naming
- Chose class/method/field names that describe the purpose of the entire method/class
- Don't use word fragments (getProjectValue is better than getProjVal)
- Don't use generic variable names like "temp" or "index"
(Exception: really short methods where usage is very straight-forward. Ok to use i,j,
it for loop indexes)
- Don't use get/set prefix unless the method really is just an accessor. If the
method does real work, it's not an accessor. (Note: we don't always follow
this rigorously, but we try).
General: (use the tool!)
- Turn on all the compiler prefs including unused temps, synthetic accessor
methods, unused imports, unused parameters, non-NLS'd strings, etc etc
- Turn on compiler warnings for javadoc
Javadoc -> Process Javadoc comments
- Malformed Javadoc comments -> warning
- Report Errors in tags -> true
- NLS your strings. Look at the Policy class.
- Compiler tasks. We have 3 that we use as a team (TODO, FIXME, XXX) Do not
add your own as this is unecessary and requires everyone on the team to change
their compiler settings in order to see these tasks.
- Sort the methods within a class alphabetically (use the sort members action).
- All classes MUST have a copyright notice.
- data type size initialization -> use meaningful values if possible,
not things like: new HashSet(65)
- Use interfaces when declaring variable types and in method signatures unless
it is necessary to use implementing class
- use accessor methods, don't access variables on other classes directly
- in general, we use the "true" case of an "if" clause
at the beginning. we also use it to exit a method early. If the whole method
is inside an "if (!foo) {}" then just say "if (foo) return".
- ignored exceptions must have a comment saying that they are being ignored
on purpose (compiler warning)
- the lines where we create new CoreExceptions and throw them can become
quite long. We usually declare the String message on the line previous to
make it easier to read.
- check for null if null could be returned (table look-ups, etc)
- should use IPath for path logic rather than Strings and concatination
- IPaths are your friend. Replace "new File(location.toOSString())"
with location.toFile();
- Don't catch Exception unless you have to. Try to catch specific exceptions.
- Don't wrap the whole method in a try {} catch {} block. This makes it hard
to generate specific error messages
- if you have nested readers/streams you should only have to call #close()
on the outside one and all wrapped streams should be closed automatically
(note: you may have to call #flush() first)
- Ensure all file I/O is buffered.
- When sharing code with others, ensure that all the code released to the
repository at least compiles.
- Policy.bind() has multiple methods, one of which accepts a single string
as an arg so you don't have to call Policy.bind("message.key", new
String[] { "text" });
NLS'ing your code: messages.properties
- all sentences which are displayed to the user must end with a period
- include parameters if possible
- remove unused messages
- make sure if the message accepts a parameter then you pass one in