64 lines
2.8 KiB
Markdown
64 lines
2.8 KiB
Markdown
# 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.
|