Breadcrumbs

= Equinox Coding Practices ?>

Coding Practices

Equinox covers a reasonably large code base. To ensure coherence
and consistency, the team follows a number of coding conventions and practices.
For the most part these conventions are supported by the Eclipse tooling (e.g.,
formatter settings) so its really a matter of setting it up and going from
there. Give yourself over to the tooling and forget about formatting. Just
let the tools do their work.

Legal

All committed contributions from non-committers must be tracked. This must be done
by using the 'contributed' keyword in bugzilla. A non-committer is someone who is not a committer on the
Eclipse Top-Level project

If the code was written in 2003, don't have 2000,2003 in the copyright.

Attribution

Contributors should feel free to identify themselves individually or by company in the code.
There are three main places this is done.

in the copyright line (first line in class comment). Here the first/main entity that
legally owns the copyright should be listed first followed by "and others". See the legal notes above.

in the Contributors section of the class comment. Here we want to capture a rough sense of who
(people and/or companies) has made contributions. We do not need to be overly specific about which
contributions. General descriptions such as "bug fixes", "performance enhancements" or "continuing
development" are fine. This is information is partly to cue the legal process to ensure
proper tracking (though the actual tracking is done through Git and Bugzilla) and partly to give contributors
visibility and acknowledgment for their contributions. People are free to put their
names in this section if they choose however, traditionally we have identified simply identified
companies/organizations here. We have opted for this approach to eliminate the continual maintenance of
the list. Contributors wanting to have their names in this section are certainly welcomed to do so in their patches.

in the @author tag in the class Javadoc. For the most part the Eclipse project team does not use @author as there are typically
a vast number of people working on and contributing to the code. Maintenance of such a list would be
quite cumbersome and poorly maintained authorship lists give a false picture of code evolution.

Use the tools

For the most part you can just use the preference template files supplied here to configure the various tools
to do the same as the rest of the team. These preference files are typically found in the .settings
directory of a project. To apply the preferences simply copy the template file from here into the .settings folder overwriting the original.
Of course, you may choose to merge the settings but beware of varying too far from the standard coding practices. The templates cover
code formatting, organize imports, code cleanup wizard settings and enabling these operations to happen automatically on save.

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.

Compiler tasks. We have 3 that we use as a team (TODO, FIXME, XXX) Do
not add your own as this is unnecessary and requires everyone on the team
to change their compiler settings in order to see these tasks.

Comments

Comments are a good thing but are not a substitute for good naming (see next section).
Comment all "non-obvious" things whether they be methods, fields,
arguments, algorithm steps, ...

Javadoc on API is essential

Follow the Javadoc guidelines as well as @since etc recommendations

Naming

Choose class/method/field names that describe the purpose of the entire
method/class.

Choose names that are semantically useful. Type-based names are taboo!
Java is strongly typed, why repeat the type in the name? For example, use
setFoo(Foo foo) is not as interesting as setFoo(Foo value).

Further, the use of semantic names makes cutting and pasting of similar code
easier and less error-prone.

Try for complete words rather than fragments (e.g., getProjectValue is
better than getProjVal).

Avoid generic variable names like "temp" or "index" (Exception:
really short methods where usage is very straight-forward an in cases of i, j,
etc for loop indexes).

get/set prefixes should be reserved for real accessors. If the method does
real work, it's not an accessor. (Note: we don't always follow this rigorously, but we try. Lazy
initialization is one such exception).

Avoid random word prefixes such as "a" and "the". They don't add value.

Internationalization

Follow the NLS guidelines and use the Eclipse NLS mechanism.

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

Exception handling

When catching exceptions, consider whether it is some low-level error that
the client should not be aware of or will not be able to interpret. Consider wrapping
in an exception with a message and API status code that will make sense to the caller.

Whenever possible let exceptions flow back to the caller through a declared
exception specified in API rather than catching and swallowing/logging ourselves.
Since our code is typically very low level, the caller often has better contextual
knowledge of whether it would more appropriate to log the exception, present to a user, or swallow it.

Only suppress or log exceptions if irrelevant to the caller and doesn't affect
the success of the operation the caller is attempting to perform.

Should only have empty catch blocks if the exception is truly impossible,
or if we completely understand all the cases where this exception can occur and
we understand that it has no effect on the success of the operation. When in doubt
log it.

Never throw generic Exception or Error - use a more specific subclass appropriate
for the error condition.

Logged exception messages should not be externalized/translated. If there
is any possibility of an exception being propagated to client code it must have
externalized messages.