Code Standards

Configuring your IDE

IntelliJ IDE: An IntelliJ code style XML file is available in the source repo at /build-resources/jetty-codestyle-intellij.xml Follow IntelliJ’s documentation to import these settings into your IDE.
Eclipse IDE: An Eclipse code style XML file is available in the source repo at /build-resources/jetty-codestyle-eclipse-ide.xml.

Java conventions

The following code sample shows some basic Java styles and conventions used throughout the Jetty codebase:

import some.exact.ClassName;      // GOOD
import some.wildcard.package.*;   // BAD!

package org.always.have.a.package;

/**
 * All classes should have a javadoc
 */
class MyClassName
{
    // Use 4 spaces to indent.
    // The code must format OK with default tab size of 8.

    private static final int ALL_CAPS_FOR_PUBLIC_CONSTANTS = 1;

    // Prefix fields with one underscore (_). This
    // convention is not mandatory, but the chosen style
    // should be used consistently within a single class.
    private Object _privateField;

    // Use getters and setters rather than public fields.
    // Braces always on new line.
    public void setPrivateField(Object privateField)
    {
        _privateField = privateField;
    }

    public Object getPrivateField()
    {
        return _privateField;
    }

    public void doSomething() throws SomeException
    {
        Object local_variable = _privateField;
        // Braces always on new line.
        if (local_variable = null)
        {
             // do Something
        }
    }
}

Logging conventions

When deciding when and what to log, bear in mind a few things:

Never use LOG.debug() without a preceding if (LOG.isDebugEnabled()).
Avoid polluting the log with very long stack traces.
Don’t routinely produce logging events in response to data sent by a user.
Only call one LOG method for a given event, to avoid generating confusingly interleaved log messages.
Never call LOG.warn() right before throwing an exception, as this will likely result in double logging the exception.
Avoid calling LOG.debug() right before throwing an exception, as this will make debug logs verbose while adding little information.

When interacting with a request or other client-provided data that result in an exception, use DEBUG-level logging:

catch (Throwable t)
{
    if (LOG.isDebugEnabled())
        LOG.debug("Something happened {} {} {}",x, y, z, t);
}

When calling into application code that throws an exception, use INFO-level logging, and gate the log with LOG.isDebugEnabled() to reduce the size of logging stack traces:

catch (Throwable t)
{
    if (LOG.isDebugEnabled())
        LOG.info("Something happened {} {} {}", x, y, z, t);
    else
        LOG.info("Something happened {} {} {} {}", x, y, z, t.toString());
}

When exceptions happen in Jetty code, and if the exception is (1) not entirely unexpected, (2) can happen relatively frequently, or (3) can potentially have a very long stack trace, you can use LOG.isDebugEnabled() to cut down on the size of the logging of the stacktrace:
```
catch (Throwable t)
{
    if (LOG.isDebugEnabled())
        LOG.warn("Something happened {} {} {}", x, y, z, t);
    else
        LOG.warn("Something happened {} {} {} {}", x, y, z, t.toString());
}
```

== By default, Jetty’s logger outputs a full stacktrace whether you call it like LOG.warn("Something happened", t) or LOG.warn("Something happened {}", t).

If you only want the log message but not the stack trace, you need to do call .toString() on the caught exception, e.g., LOG.warn("Something happened {}", t.toString()). ==