-
Notifications
You must be signed in to change notification settings - Fork 8
Coding guidelines
Guidelines for developing on EAd2.
slf4j - We use slf4j as our logging-abstraction-layer; this allows us to change logging implementation at any time (currently, we use slf4j-simple)
gwt - gwt's logging is a very simple bridge to java.util.Logging, which is already emulated by gwt.
logger - Each implementation class should have a
private static final Logger logger = LoggerFactory.getLogger("NameOfClass");
exceptions - Should always be logged with a message
e.printStackTrace(); // BAD: does not show up in log
logger.warn(e.getMessage(), e); // BAD: e.getMessage() already in e
logger.warn("Error loading {} from '{}'", bar, baz, e); // GOOD: provides context
{}-placeholders - Use {}-placeholders for your exception arguments. They are easier to read and faster than string-concatenation. If there is any chance that your arguments may have spaces around them, quote placeholders like this: '{}' to make them obvious in the output.
Example snippet:
public static Image loadImage(String resourceName) {
try {
return ImageIO.read(ClassLoader.getSystemResourceAsStream(resourceName));
} catch (IOException e) {
logger.warn("Image not found: '{}'", resourceName);
return placeholderImage();
}
}
levels - when to use each logging level:
level | use |
error | very bad; something that should never happen in normal use |
warn | bad, but may sometimes happen in normal use |
info | typical in normal use; high-level information |
debug | low-level information; usually best to ignore |
trace | so low-level that it should almost never be useful |
use finally - always close your resources within a finally-clause reuse - Getting those finally-clauses right is difficult; write them once and reuse them as much as possible. exceptins in close() - log all exceptions - even the ones you may get when calling close(). For example, a BufferedOutputStream may not attempt to write until it is closed; if you ignore the error, you will never know it failed.
Example snippet:
// os is an OutputStream of some type
try {
// ...
} finally {
if (os != null) try {
os.close();
} catch (Exception e) {
logger.error("error doing baz on {}", bar, e);
}
}