neqsim-code-hygiene · v1.0.0 · 2026-09-18 · sha256 8ca0467254295624
neqsim-code-hygiene v1.0.0A
Immutable. This exact content is served forever at /api/v1/blob/8ca0467254295624.
---
name: neqsim-code-hygiene
version: "1.0.0"
description: "Fix formatting, Checkstyle, Spotless, and JavaDoc build failures in NeqSim Java code. USE WHEN: the build fails on spotless:check, checkstyle:check, or javadoc:javadoc; a PR shows formatting/import-order/JavaDoc violations; or you edited any .java file and need to make it CI-clean. Covers the exact recurring errors (JavadocParagraph <p>, orphan </p> after lists, single-line @param/@return, import ordering, HTML5 tables, unused variables) and the fix-and-verify loop."
last_verified: "2026-09-18"
---
# 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:
```bash
./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:
```bash
./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:
```java
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.
```java
// 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>").
```java
// 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:
```bash
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:
```java
// 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:
```java
/**
* Sets the pump speed.
*
* @param speed the pump speed in rpm
*/
public void setPumpSpeed(double speed) { ... }
```
## JavaDoc: HTML5 Tables
```java
// 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
| Error | Cause | Fix |
|-------|-------|-----|
| `reference not found` | `@see IEC 61508` (plain text) | Move the standard into the description text; `@see` only takes `ClassName`/`#method` |
| `bad use of '>'` | Lambda `->` or `>` in a JavaDoc code example | Use `>`, or rewrite the lambda as an anonymous class |
| `no @param for X` / `no @return` / `no @throws for X` | Missing tag (applies to private methods too) | Add the tag; every `throws` clause needs a matching `@throws` |
| `semicolon missing` / `malformed HTML` | Unbalanced tag in JavaDoc | Check tag nesting; lists close the paragraph implicitly |
## 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.
## Deprecated Method / Constructor Calls (`[deprecation]` warnings)
Calling an API marked `@Deprecated` produces a `[deprecation]` compiler warning
(`uses or overrides a deprecated API`). NeqSim treats these as debt to pay down: replace
the call with the successor named in the member's `@deprecated` JavaDoc.
**Find the successor — never guess.** Read the deprecated member's JavaDoc; the
`@deprecated` tag states the replacement:
```java
/**
* @deprecated use {@link #getFluid()} instead
*/
@Deprecated
public SystemInterface getThermoSystem() { ... }
```
**Migrate the call site** (do NOT change the deprecated method's body):
```java
// WRONG — deprecated call:
SystemInterface sys = stream.getThermoSystem();
// CORRECT — successor from the @deprecated note:
SystemInterface sys = stream.getFluid();
```
Find deprecated usages across the tree:
```bash
# every call site the compiler warned about
./mvnw -q compile 2>&1 | grep -i deprecat
# or search for a specific retired method by name
grep -rn "getThermoSystem(" src/main/java src/test/java
```
Rules and cautions:
- Prefer `vscode_listCodeUsages` / the rename provider to migrate every call site of a
retired member consistently, rather than editing one file at a time.
- Verify the successor's **signature and semantics** (units, return type, side effects)
match — a deprecation replacement is not always a drop-in; check the JavaDoc.
- If the `@deprecated` tag gives no replacement, or the successor changes behaviour, do
NOT blind-swap it — leave it and flag it for the owner.
- Do NOT delete the deprecated member itself or strip its `@Deprecated` annotation; other
callers (and downstream users) may still depend on it. This skill fixes *call sites*.
- Overriding a deprecated method also warns — annotate the override `@Deprecated` too, or
re-target it to the successor.
- After migrating, re-run `./mvnw -q compile` and confirm the `[deprecation]` warning for
that member is gone, then run the full verify loop.
## Common Mistakes
| Mistake | Fix |
|---------|-----|
| Running only `spotless:check` and expecting it to fix files | Run `spotless:apply` to actually reformat |
| Expecting Spotless to sort imports or fix JavaDoc | Do those by hand; Spotless only touches formatting |
| Adding `</p>` to "close" a `<p>` | JavaDoc `<p>` is a separator — never add `</p>` |
| Leaving `</p>` after `</ul>`/`</ol>` | Remove it — the list already closed the paragraph |
| Committing with `--no-verify` to skip the gate | Never bypass; fix the violation |
| Hand-indenting long method chains | Let `spotless:apply` wrap them |
| Guessing a deprecated method's replacement | Read the `@deprecated` JavaDoc tag for the named successor |
| Deleting a deprecated member to clear a warning | Fix the *call site*; other callers may still need the member |
## Validation Checklist
- [ ] `./mvnw spotless:apply` run, files re-`git add`ed
- [ ] `./mvnw spotless:check` passes
- [ ] `./mvnw checkstyle:check` passes (imports sorted, `<p>` preceded by blank line, no single-line JavaDoc)
- [ ] `./mvnw javadoc:javadoc` passes (no orphan `</p>`, tables have `<caption>`, no plain-text `@see`)
- [ ] Every method with a `throws` clause has a matching `@throws`
- [ ] No `[deprecation]` warnings — call sites migrated to the successor named in the `@deprecated` tag
- [ ] Code still compiles with Java 8 (see `neqsim-java8-rules`)
## References
- `.config/checkstyle_neqsim.xml` — Checkstyle rules (Google style + overrides)
- `.config/neqsim_formatter.xml` — Eclipse formatter profile used by Spotless
- `neqsim-java8-rules` skill — forbidden Java 9+ features and JavaDoc requirements
- `AGENTS.md` / `.github/copilot-instructions.md` — Spotless and JavaDoc mandates