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 precedingif (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 withLOG.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())
.
==