JavaTest Method Commentation Design

Goal

Make every Java method under javaTest/src/main/java and javaTest/src/test/java readable to a developer who is learning the WCS simulation, without changing runtime behavior, public APIs, test data, or test outcomes.

Scope

Cover all Java source files under javaTest/src/main/java and javaTest/src/test/java.
Cover every constructor, public method, private method, package-visible method, getter, helper, and test method.
Add class-level context where a class represents a domain concept, algorithm, adapter, simulator, result object, or test fixture.
Preserve generated resources, output evidence, Maven configuration, and all non-Java files unchanged.

Comment Style

Use Chinese Javadoc immediately above each method.
State the method's responsibility first. Add inputs, return meaning, state changes, ordering rules, failure behavior, or invariants only when they help the reader understand behavior beyond the signature.
Use @param, @return, and @throws when a method has meaningful inputs, results, or deliberate failure behavior.
Constructors describe the object state that is established.
Simple getters receive concise comments identifying the exposed state rather than repeating implementation details.
Test methods describe the business scenario, fixture condition, and assertion intent. Test helpers describe the deterministic data or topology they build.
Use short line or block comments only before non-obvious algorithmic sections, including path construction, resource reservation/release, fault recovery, watchdog progress, report metrics, and endpoint mapping. Do not annotate each statement mechanically.

Content Rules

Comments describe current code, never intentions that the implementation does not satisfy.
Keep domain terms consistent: task, vehicle, route, node, edge, resource, HOLD, redispatch, PLC, WMS, archive, history path, and physical endpoint.
Distinguish historical comparison fields from fields that affect current dispatch decisions.
Preserve English identifiers, enum values, exception messages, and protocol names; explain their business meaning in Chinese when needed.
Avoid comments that claim field-test or production behavior. The existing boundary remains an in-memory simulation unless a class actually controls a real integration.

Verification

Use a source scan to confirm every Java method and constructor has a immediately preceding Javadoc block.
Compile and run mvn clean test from javaTest after all comment-only edits.
Review git diff --check and confirm the diff contains comments only.

Non-Goals

No refactoring, renaming, logic changes, formatting-only rewrites, or new features.
No modification to ruoyi-* production modules.

2.8 KiB Raw Blame History