Skip to content
This repository has been archived by the owner on Dec 20, 2019. It is now read-only.

Coding guidelines

manuel-freire edited this page Sep 21, 2012 · 3 revisions

Coding Guidelines for EAd2

Introduction

Guidelines for developing on EAd2.


Logging & Exceptions

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

Streams and IO

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);
       }
    }