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