99 lines
3.1 KiB
Markdown
99 lines
3.1 KiB
Markdown
# Lardon3D — Source Comment Audit
|
|
|
|
## Status
|
|
|
|
```text
|
|
SOURCE_COMMENT_AUDIT=PASS
|
|
SOURCE_COMMENT_REMEDIATION=PASS
|
|
SOURCE_COMMENT_SCOPE=include/lardon3d/** + src/**
|
|
SOURCE_COMMENT_LANGUAGE=ENGLISH
|
|
SOURCE_CODE_BEHAVIOR_CHANGED=NO
|
|
```
|
|
|
|
The audit covered 148 C/C++ source/header files under `include/lardon3d/**` and `src/**`.
|
|
|
|
The initial static inventory reported:
|
|
|
|
```text
|
|
comment blocks 807
|
|
raw non-English lexical candidates 33
|
|
actual French comment blocks 29
|
|
English false positives 4
|
|
stale-contract candidates 0
|
|
raw unannotated-public declarations 324
|
|
```
|
|
|
|
## Remediation
|
|
|
|
All 29 actual French source comments were translated to English.
|
|
|
|
The four raw language-detector false positives were already English and were left unchanged.
|
|
|
|
The remediation touched comments only. A file-level lexical comparison removed comments entirely and verified that every non-comment source
|
|
byte remained identical before and after the declared replacements.
|
|
|
|
No executable UI/error string was changed in this pass. UI language is a separate explicitly scoped
|
|
implementation pass.
|
|
|
|
## Stale and misleading comments
|
|
|
|
The lexical stale-contract pass found zero candidate comments.
|
|
|
|
No scientific threshold, schema version, Task Kind, resource contract, persistence identity or FROZEN
|
|
boundary was changed by this audit.
|
|
|
|
## Public API adjacency heuristic
|
|
|
|
The first inventory reported 324 public declarations without an immediately adjacent comment.
|
|
|
|
That number is **informational only**, not 324 defects.
|
|
|
|
The repository Source Comment Contract requires comments where WHY, CONTRACT, INVARIANT, OWNERSHIP,
|
|
IDENTITY, persistence ordering, restart, cancellation, concurrency, resource accounting or a FROZEN
|
|
boundary is non-obvious. It does not require one redundant comment for every getter, thin wrapper,
|
|
paired create/load/list function or declaration already covered by a surrounding contract block.
|
|
|
|
Therefore absence of an adjacent comment alone is not a valid
|
|
`UNDER_COMMENTED`/`SEVERELY_UNDER_COMMENTED` finding.
|
|
|
|
Future audits must review semantic contract coverage rather than using declaration adjacency as a
|
|
blanket failure criterion.
|
|
|
|
## Source Comment Contract
|
|
|
|
Production source comments:
|
|
|
|
- are English;
|
|
- explain non-obvious WHY/CONTRACT/INVARIANT facts;
|
|
- preserve ownership and lifetime boundaries;
|
|
- preserve persistence/restart ordering;
|
|
- preserve concurrency/resource-accounting boundaries;
|
|
- preserve scientific identity and FROZEN constraints;
|
|
- do not paraphrase obvious code line-by-line;
|
|
- are updated when behavior changes.
|
|
|
|
## Validation
|
|
|
|
The remediation runner requires:
|
|
|
|
```text
|
|
branch = docs-audit
|
|
no unrelated worktree changes
|
|
all expected old comments match exactly once
|
|
file-level source with all comments removed remains byte-for-byte identical
|
|
no strong French-comment candidate remains
|
|
git diff --check passes
|
|
```
|
|
|
|
## Phase state
|
|
|
|
```text
|
|
DOCUMENTATION_FINDING_REMEDIATION=PASS
|
|
DOCUMENTATION_LANGUAGE_NORMALIZATION=IN_PROGRESS
|
|
|
|
SOURCE_COMMENT_AUDIT=PASS
|
|
SOURCE_COMMENT_REMEDIATION=PASS
|
|
|
|
PRODUCT_DEFINITION=PASS/FROZEN
|
|
PROMPT_TREE=NEXT
|
|
```
|