Joseph Doherty
66 lines
2.3 KiB
Markdown
66 lines
2.3 KiB
Markdown
# Java Style Guide
|
|
|
|
This guide defines Java conventions for the MXAccess Gateway Java client
|
|
library, CLI, and tests.
|
|
|
|
## Baseline
|
|
|
|
- Target the Java version defined by the client build, with Java 21 preferred.
|
|
- Use Gradle unless the repository standardizes on Maven.
|
|
- Apply a formatter such as Spotless or Google Java Format when configured.
|
|
- Keep generated protobuf code separate from handwritten wrappers.
|
|
|
|
## Source Documentation
|
|
|
|
- Maintain the existing documentation style in the file, package, and
|
|
surrounding component.
|
|
- Write comments that include business-specific or domain-specific context when
|
|
that context is available from the code, surrounding docs, or naming.
|
|
- Use Javadoc for public APIs when behavior, parity constraints, or security
|
|
requirements are not obvious from the signature.
|
|
- Avoid comments that restate syntax or control flow.
|
|
|
|
## Packages
|
|
|
|
- Use lowercase package names under `com.zb.mom.ww.mxgateway`.
|
|
- Keep client library code separate from CLI code.
|
|
- Keep generated protobuf classes in a generated package.
|
|
- Do not expose implementation-only transport helpers as public API.
|
|
|
|
## Naming
|
|
|
|
- Use `PascalCase` for classes, records, interfaces, and enums.
|
|
- Use `camelCase` for methods, fields, parameters, and local variables.
|
|
- Use `UPPER_SNAKE_CASE` for constants.
|
|
- Use MXAccess terms consistently: `serverHandle`, `itemHandle`,
|
|
`mxStatusProxy`, and `hResult`.
|
|
|
|
## API Design
|
|
|
|
- Prefer immutable options objects with builders for public configuration.
|
|
- Implement `AutoCloseable` for clients and sessions that own resources.
|
|
- Provide async methods with `CompletableFuture` where useful, but keep a
|
|
blocking API for simple CLI workflows.
|
|
- Expose raw generated protobuf messages where parity tests need them.
|
|
|
|
## Errors
|
|
|
|
- Use typed exceptions for gateway, authentication, authorization, session,
|
|
worker, command, and MXAccess failures.
|
|
- Preserve raw command replies in command exceptions when available.
|
|
- Redact API keys, passwords, and secured write values in `toString`, logs, and
|
|
CLI output.
|
|
|
|
## Streaming
|
|
|
|
- Cancel gRPC calls explicitly when callers stop consuming streams.
|
|
- Do not reorder, coalesce, or drop events in client code.
|
|
- Avoid unbounded queues in async stream helpers.
|
|
|
|
## Tests
|
|
|
|
- Use JUnit 5.
|
|
- Use in-process gRPC servers for unit tests.
|
|
- Keep live gateway tests behind `MXGATEWAY_INTEGRATION=1` and JUnit
|
|
assumptions.
|