Introduction

This page outlines the coding conventions used in HtmlUnit. All code contributions to this project are expected to adhere to these conventions.

The primary purpose of shared coding conventions is to ensure consistency, legibility, and maintainability across the codebase. The guidelines detailed in this document reflect best practices adopted to keep the codebase robust over time.

We use Checkstyle to enforce coding standard rules automatically. Rules enforced by Checkstyle are only documented below if they require additional explanation. You can run Checkstyle using Maven:

mvn checkstyle:checkstyle

Unit Tests

All code must have thorough test coverage built with the JUnit testing framework. Writing code test-first is strongly encouraged. Execute tests with the following Maven target:

mvn test

Abbreviations

Abbreviations obscure intent and should generally be avoided in variable and method names. Explicit, descriptive naming is preferred to ensure self-documenting code.

The following table lists the only universally permitted abbreviations. Any abbreviation not included in this list is not allowed:

To propose adding a new abbreviation to this list, start a thread on the developer mailing list. If no maintainers object, it will be added to the convention guidelines.

The final Keyword

The final keyword should be applied wherever possible. It communicates intent clearly to developers and the compiler, helping prevent unintended reassignments and identifying potential state errors early.

Declare variables final to indicate they are assigned only once:

private final int fooCount = 12;

Declare method parameters final to prevent accidental parameter reassignment:

public void setFooList(final List<Foo> fooList) {

Declare methods final to indicate they cannot be overridden in subclass implementations:

public final int getFooCount() {

Declare classes final when they are not designed for inheritance:

public final class FooCounter {

Import Statements

Use explicit, fully qualified import statements instead of wildcard imports:

import java.util.List;
import java.util.ArrayList;

Do not use wildcard imports:

import java.util.*;

Explicit imports make dependencies transparent when reading and reviewing code. IDEs like Eclipse and IntelliJ IDEA can be configured to manage imports and prune unused ones automatically.

Indentation

Indent code using spaces instead of tabs. Use four (4) spaces per indentation level.

Deprecation

When public API elements must be retired, deprecate the API using the JavaDoc @deprecated tag. Deprecated code must remain in the codebase for at least 6 months and across at least 2 major/minor releases.

When direct deprecation is not feasible, log the change in the Change Log flagged with INCOMPATIBLE CHANGE to make breaking updates explicit.