Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 | Dont |
| 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 Oracles 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
Expand Down
10 changes: 5 additions & 5 deletions src/main/adoc/project-requirements.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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)
Expand Down