Java Coding Conventions

Java Coding practices in the DITA-OT

The core developers on the DITA Open Toolkit generally try to keep several coding practices and design patterns in mind when adding to the toolkit's Java code. If you are interested in digging around in the DITA Open Toolkit, or in contributing Java patches back to the core toolkit, you may want to keep these practices in mind.

General Code Conventions

• Always use the specialized form to refer to elements. That is, do not write code that uses the "indexterm" element name; instead, code should depend upon the class attribute token. That is, use Constants.TOPIC_INDEXTERM instead.
• APIs should not be removed without a lot of thought and preparation.
• All coding must use Java 17.

The DITA-OT project uses Prettier to format Java code. Run npm run fmt before committing code changes; GitHub Actions are used to check that all code modifications have been formatted correctly.

The guidelines set forth in Effective Java, Second Edition should be followed when possible. Example principles include:

• Item 15: Minimize mutability
• Item 23: Don't use raw types in new code
• Item 44: Write doc comments for all exposed API elements
• Item 46: Prefer for-each loops to traditional for loops
• Item 58: Use checked exceptions for recoverable conditions and run-time exceptions for programming errors

In addition, prefer Streams when possible and use new features of the Java version liberally.

Boilerplate

As with other coding modules, each Java file should contain a statement at the top indicating the copyright holder, and indicating the license. All code contributed to the toolkit must be compatible with the Apache 2.0 license. The default boilerplate is

/*
 * This file is part of the DITA Open Toolkit project.
 *
 * Copyright <year> <author or company>
 *
 * See the accompanying license.txt file for applicable licenses.
 */

Replace placeholders for year and code author. Do not change the license and copyright boilerplate in existing files.

Documenting code

Java code should be documented using Javadoc comment. Instead of using in-line comments to document the code, split the code into smaller methods and document each method. Do not add in-line change documents for bug fixes, git blame is intended for that purpose.

Unit tests

Each Java class should have an associated JUnit test case. Test cases must create all temporary files into a temporary folder and delete them after the test is run.