diff --git a/AGENTS.md b/AGENTS.md index afe8075..1a9e192 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,11 +19,11 @@ LLM-based agents can accelerate development only if they respect our house rules **Goal:** Every Javadoc block should add information you cannot glean from the method signature alone. Anything else is noise and slows readers down. -| Do | Don’t | +| Do | Don't | |----|-------| | State *behavioural contracts*, edge-cases, thread-safety guarantees, units, performance characteristics and checked exceptions. | Restate the obvious ("Gets the value", "Sets the name"). | | Keep the first sentence short; it becomes the summary line in aggregated docs. | Duplicate parameter names/ types unless more explanation is needed. | -| Prefer `@param` for *constraints* and `@throws` for *conditions*, following Oracle’s style guide. | Pad comments to reach a line-length target. | +| Prefer `@param` for *constraints* and `@throws` for *conditions*, following Oracle's style guide. | Pad comments to reach a line-length target. | | Remove or rewrite autogenerated Javadoc for trivial getters/setters. | Leave stale comments that now contradict the code. | The principle that Javadoc should only explain what is *not* manifest from the signature is well-established in the diff --git a/src/main/adoc/project-requirements.adoc b/src/main/adoc/project-requirements.adoc index 5e58dfb..ba5a181 100644 --- a/src/main/adoc/project-requirements.adoc +++ b/src/main/adoc/project-requirements.adoc @@ -12,18 +12,18 @@ JRC-FN-003 :: The library *MUST* support the compilation of nested classes conta JRC-FN-004 :: Callers *MUST* be able to supply a custom `ClassLoader`; default is the current context loader. JRC-FN-005 :: A _debug mode_ *MUST* emit `.java` and `.class` artefacts to configurable directories for IDE inspection. -=== Non-Functional – Performance (NF-P) +=== Non-Functional - Performance (NF-P) -JRC-NF-P-006 :: First-time compilation of a <1 kLoC class *SHOULD* complete in ≤ 500 ms on a 3 GHz x86-64 CPU. +JRC-NF-P-006 :: First-time compilation of a <1 kLoC class *SHOULD* complete in <= 500 ms on a 3 GHz x86-64 CPU. JRC-NF-P-007 :: Steady-state invocation latency of compiled methods *MUST* be within 10 % of statically compiled code. JRC-NF-P-008 :: Peak metaspace growth per 1 000 unique dynamic classes *MUST NOT* exceed 50 MB. -=== Non-Functional – Security (NF-S) +=== Non-Functional - Security (NF-S) JRC-NF-S-009 :: The API *MUST* allow callers to plug in a source-code validator to reject untrusted or malicious input. JRC-NF-S-010 :: Compilation *MUST* occur with the permissions of the hosting JVM; the library supplies _no_ elevated privileges. -=== Non-Functional – Operability (NF-O) +=== Non-Functional - Operability (NF-O) JRC-NF-O-011 :: All internal logging *SHALL* use SLF4J at `INFO` or lower; compilation errors log at `ERROR`. JRC-NF-O-012 :: A health-check helper *SHOULD* verify JDK compiler availability and JVM module flags at start-up. @@ -32,7 +32,7 @@ JRC-NF-O-013 :: The library *MUST* expose a counter metric for successful and fa === Test / QA (TEST) JRC-TEST-014 :: Unit tests *MUST* cover >= 90 % of public API branches, including happy-path and diagnostics. -JRC-TEST-015 :: Concurrency tests *MUST* exercise ≥ 64 parallel compile requests without race or deadlock. +JRC-TEST-015 :: Concurrency tests *MUST* exercise >= 64 parallel compile requests without race or deadlock. JRC-TEST-016 :: A benchmark suite *SHOULD* publish compile latency and runtime call performance on CI. === Documentation (DOC)