Neqsim Code Hygiene

NeqSim Code Hygiene: Formatting, Checkstyle, Spotless & JavaDoc Fixes

This skill is the fix-it playbook for the code-quality gates that fail NeqSim CI: spotless:check (formatting), checkstyle:check (style, imports, JavaDoc structure), and javadoc:javadoc (HTML5-valid JavaDoc). It maps each recurring error message to its exact cause and fix, and gives the mandatory verify loop. For the separate rule set on which Java language features are allowed, load neqsim-java8-rules.

When to Use This Skill

• The build fails on spotless:check, checkstyle:check, or javadoc:javadoc.
• A PR or the Problems panel shows formatting, import-order, or JavaDoc violations.
• You created or edited ANY .java file (main, test, or examples) and must make it CI-clean.
• You pasted a JavaDoc/error block and asked "fix errors like this".

The Fix-and-Verify Loop (do this every time)

1. Format first — Spotless fixes whitespace/indentation but NOT import order or JavaDoc content:

   ./mvnw spotless:apply

2. Fix Checkstyle/JavaDoc by hand — imports, <p> tags, single-line JavaDoc, tables (below).
3. Verify each gate on the touched files, then the whole set:

   ./mvnw spotless:check
   ./mvnw checkstyle:check
   ./mvnw javadoc:javadoc

4. Re-run spotless:apply after hand edits (JavaDoc edits can change wrapping), then git add.
5. NEVER bypass with git commit --no-verify.

Order matters: hand-fix JavaDoc/imports, then spotless:apply last so the committed file is both style-correct and formatter-clean.

Spotless

• AI-generated Java is not auto-formatted; a single unformatted file fails the whole CI build.
• Profile: Eclipse .config/neqsim_formatter.xml (pom.xml), applied to src/main/java and src/test/java.
• spotless:apply fixes: indentation (2 spaces), trailing whitespace, blank lines, brace placement, line wrapping of long method chains and string concatenations.
• spotless:apply does NOT fix: import ordering, JavaDoc content/structure, unused variables.
• Convenience wrapper also available: python devtools/run_spotless.py / devtools/run_spotless.sh.

Checkstyle: Import Ordering

Config: .config/checkstyle_neqsim.xml (Google style + project overrides). Imports must be alphabetical by full path, grouped in this order with the groups appearing top-to-bottom:

import com.google.gson.JsonObject;      // com.*
import java.util.HashMap;               // java.*  (HashMap before HashSet before List...)
import java.util.HashSet;
import java.util.List;
import neqsim.thermo.system.SystemInterface;  // neqsim.*
import org.apache.logging.log4j.LogManager;   // org.*  (goes last)
import org.apache.logging.log4j.Logger;

Rule: sort strictly by the full import string. java.util.HashMap sorts before java.util.HashSet; org.* comes after neqsim.*. No blank lines inside a group unless the project's config requires group separation — match the surrounding file.

Checkstyle: JavadocParagraph (<p> errors)

The JavadocParagraph rule requires that every <p> tag is preceded by a blank JavaDoc line (a lone *). This is the most common failure.

// WRONG — <p> immediately after a heading/text line:
/**
 * <h2>Hardy Cross Method</h2>
 * <p>Balances loop flows iteratively...</p>
 */

// CORRECT — blank ` *` line before <p>:
/**
 * <h2>Hardy Cross Method</h2>
 *
 * <p>Balances loop flows iteratively...
 */

Notes:

• Do NOT self-close or add a closing </p> — JavaDoc treats <p> as an opening separator.
• The blank line rule applies before every <p>, including ones after <h2>, <pre>, </ul>.

JavaDoc: Orphan </p> After a List (javadoc:javadoc HTML error)

Starting a <ul> or <ol> implicitly closes the current paragraph. A </p> after the list has no matching <p> and breaks HTML5 JavaDoc ("unexpected end tag: </p>").

// WRONG — orphan </p> after the list closes:
/**
 * <p>Supported modes:
 * <ul>
 *   <li>Sequential</li>
 *   <li>Newton-Raphson</li>
 * </ul>
 * </p>
 */

// CORRECT — drop the trailing </p>:
/**
 * <p>Supported modes:
 *
 * <ul>
 *   <li>Sequential</li>
 *   <li>Newton-Raphson</li>
 * </ul>
 */

Find them fast across a file/tree:

grep -rnE '^\s*\*\s*</p>' src/main/java src/test/java

Checkstyle: Single-Line @param / @return JavaDoc

A single-line JavaDoc like /** @return the pump speed */ triggers THREE violations: missing summary sentence, not-multiline, and tag-not-preceded-by-blank-line. Expand it:

// WRONG:
/** @return the pump speed in rpm */
public double getPumpSpeed() { ... }

// CORRECT — summary sentence, blank line, then the tag:
/**
 * Returns the pump speed.
 *
 * @return the pump speed in rpm
 */
public double getPumpSpeed() { ... }

Same shape for setters/params:

/**
 * Sets the pump speed.
 *
 * @param speed the pump speed in rpm
 */
public void setPumpSpeed(double speed) { ... }

JavaDoc: HTML5 Tables

// WRONG — deprecated summary attribute, no caption:
/**
 * <table summary="modes">
 * <tr><th>Mode</th></tr>
 * </table>
 */

// CORRECT — <caption> element, no summary attribute:
/**
 * <table>
 * <caption>Solver modes</caption>
 * <tr><th>Mode</th></tr>
 * </table>
 */

JavaDoc: Other Recurring Errors

Unused Variables / Fields (compiler warnings, not Checkstyle failures)

get_errors may report unused locals/fields after cleanup. They do NOT fail the CI gates but are worth clearing:

• Unused local with a side-effect-free initializer (e.g. double viscosity = ...;) → delete it.
• Unused field that is part of a data model (has no getter/setter yet) → leave it unless the owner confirms; deleting model state can break serialization or future use.