This page last changed on Dec 10, 2007 by pfragemann.
 | These are guidelines related to the development of Confluence. The guidelines mainly apply to Atlassian employees, but reading them should provide insight for third-party plugin developers as well, so we decided to make them public. |
Randomly sorted guidelines.
- Don't catch Exception unless that's all you're having thrown to you.
- Don't declare that you throw Exception ever.
- Both rules #1 and #2 apply to RuntimeException as well.
- Don't catch Throwable if you want to continue breathing.
- Rule #4 applies to Error and any subclasses of Error as well.
- Don't catch, log and rethrow.
- Familiarise yourself with the standard RuntimeException subclasses (IllegalStateException, IllegalArgumentException, UnsupportedOperationException, IndexOutOfBoundsException), and use them in preference to creating your own runtime exception class.
- For example, if the problem is that an object reference (or "pointer") which you didn't expect to be null is in fact null, why not throw a NullPointerException?
- If you explicity throw any RuntimeException in a method, document it in the method's @throws Javadoc like you would a checked exception.
Meaningful exceptions
Where possible create, document and throw meaningful unchecked exceptions. For example, write this:
public class MyGroupManager
{
/**
* ...
* @throws InvalidGroupException if the group cannot be handled
*/
public void handleGroup(Group group) throws InvalidGroupException
{
if (!isValidGroup(group))
throw new InvalidGroupException("Group is invalid: " + group.toString());
// do something with the group
}
}
public class InvalidGroupException extends RuntimeException
{
// ...
}
In preference to this:
public class EvilGroupManager
{
public void handleGroup(Group group)
{
if (!isValidGroup(group))
throw new RuntimeException("Group is invalid: " + group.toString());
// do something with the group
}
}
The latter implementation is not as good because it gives the calling code very little discretion as to what kind of exceptions it wants to handle.
|