110 lines
6.3 KiB
Markdown
110 lines
6.3 KiB
Markdown
# Comment and reference inventory
|
|
|
|
Status: **complete at the recorded baseline**.
|
|
|
|
## Classification standard
|
|
|
|
A durable source comment should make the local invariant, retail behavior, or
|
|
non-obvious constraint understandable without requiring a private conversation.
|
|
External provenance is useful when it points to a stable, obtainable source.
|
|
Campaign chronology is useful in research/decision records but usually not as
|
|
the primary explanation inside production code.
|
|
|
|
Comments will be classified as:
|
|
|
|
- **Durable invariant/provenance:** explains why/order/math and cites a stable
|
|
retail symbol, public document, or owned design contract.
|
|
- **Useful but context-dependent:** technically valuable, but requires an issue,
|
|
campaign, commit, or unavailable reference to understand.
|
|
- **Historical residue:** describes how an older implementation changed rather
|
|
than what the current code guarantees.
|
|
- **Diagnostic/apparatus residue:** names a temporary probe, rejected attempt,
|
|
manual gate, or one-off capture in maintained code.
|
|
- **Misleading/stale:** contradicts current code or an active authority.
|
|
- **Noise:** restates code, uses phase labels as structure, or preserves no
|
|
decision a maintainer needs.
|
|
|
|
## Initial inventory
|
|
|
|
A Roslyn trivia scan over all 1,325 owned C# files found 37,734 actual comment
|
|
trivia nodes, including 9,516 XML-documentation comments. Of those comments,
|
|
2,172 contain a campaign/slice/phase/checkpoint or commit-hash reference, 1,016
|
|
contain an issue-number reference, 1,049 name an external/reference oracle,
|
|
617 contain probe/temporary/workaround/diagnostic language, 143 contain
|
|
OpenGL/ImGui or GL-owner terminology, and 16 contain TODO/FIXME/HACK/XXX
|
|
markers. Categories overlap and occurrence does not by itself make a comment
|
|
bad; the figures identify the review surface without matching strings or
|
|
identifiers.
|
|
|
|
| Area | Comment trivia | Campaign/history | Issue refs | External refs | Old graphics | Probe/workaround |
|
|
|---|---:|---:|---:|---:|---:|---:|
|
|
| App | 18,009 | 1,215 | 480 | 121 | 107 | 244 |
|
|
| Core | 8,723 | 399 | 322 | 452 | 4 | 224 |
|
|
| Runtime | 5,813 | 227 | 123 | 112 | 1 | 46 |
|
|
| Core.Net | 2,545 | 156 | 37 | 328 | 0 | 23 |
|
|
| UI.Abstractions | 899 | 69 | 12 | 11 | 22 | 18 |
|
|
| Headless | 534 | 42 | 21 | 13 | 0 | 29 |
|
|
| All remaining source/tools | 1,211 | 64 | 21 | 12 | 9 | 33 |
|
|
|
|
High-signal examples already queued for review include:
|
|
|
|
- `src/AcDream.App/Rendering/Wb/WbDrawDispatcher.cs`, whose comments mix retail
|
|
symbols and durable draw invariants with issue numbers, campaign slice
|
|
migrations, deleted GL-arm history, and named throwaway probes across a
|
|
3,773-line class.
|
|
- `src/AcDream.Headless/Policies/HeadlessBotPolicy.cs`, whose production XML
|
|
documentation contains campaign contracts, temporary evidence gathering,
|
|
an open issue, and disabled diagnostic behavior.
|
|
- Tool entry points that identify themselves primarily by the issue/campaign
|
|
that created them, without a maintained support/archival classification.
|
|
- `src/AcDream.Core.Net/WorldSession.cs` contains 69 campaign-history comments
|
|
and 47 external-reference comments inside a 3,754-line transport/session
|
|
owner; `VendorUiController.cs` contains 71 campaign-history comments.
|
|
- `AcDream.UI.Abstractions` still documents ImGui capture and panel behavior in
|
|
interfaces used by the retained client after the ImGui backend was deleted.
|
|
|
|
The exact project counts and confirmed high-risk classes above are the final
|
|
inventory. It intentionally does not propose mass deletion: durable retail
|
|
symbols and local invariants are valuable, while stale backend claims,
|
|
personal paths, unavailable-reference paths, campaign narration, and failed
|
|
temporary-cleanup markers require targeted correction.
|
|
|
|
## Confirmed reference-context problems
|
|
|
|
- “holtburger” appears 163 times across 52 owned source files and 50 times
|
|
across 23 test files. Twenty-three source/test files contain a literal
|
|
`references/holtburger/...` path, but the only tracked reference root is the
|
|
uninitialized `references/WorldBuilder` gitlink. The citations are often
|
|
valuable independent corroboration, but a new maintainer cannot inspect the
|
|
cited code, commit, or license from this checkout. Examples include
|
|
`Core/Chat/CombatChatTranslator.cs:15-16`,
|
|
`Runtime/Chat/ChatInputParser.cs:6-7`, and numerous Core.Net wire-layout
|
|
comments. Stable public URL+revision or an owned evidence extract is needed;
|
|
a private/missing working-copy path is not durable provenance.
|
|
- Current source comments still describe deleted behavior. Examples include
|
|
`UiDatElement.cs:24-29` claiming `TextureCache.UploadRgba8` sets
|
|
`GL_REPEAT`, `FrameScreenshotController.cs:7-10,61,123-247` documenting a GL
|
|
thread/default-framebuffer path no production caller uses,
|
|
`FrameProfiler.cs:11-30` retaining an ImGui timing stage, and the dead panel
|
|
interfaces described in F-012. These are misleading, not merely historical.
|
|
- `RenderingDiagnostics.cs` and `PortalVisibilityBuilder.cs` contain multiple
|
|
comments explicitly ordering future maintainers to strip “throwaway” or TEMP
|
|
apparatus after May/June investigations that are already closed. The code
|
|
remained through the Vulkan cutover, so those comments are failed cleanup
|
|
markers rather than actionable ownership. F-016 records the executable debt.
|
|
- Campaign/issue references are useful as secondary provenance, but many source
|
|
comments make the chronology the primary explanation (for example the long
|
|
“Night-round review F14” house-marker note in
|
|
`MapPageController.cs:449-481`). A durable local invariant and current
|
|
reachability/support status should lead; campaign labels and dates belong in
|
|
linked research or decision records.
|
|
- Personal-machine paths are also embedded as provenance. The literal
|
|
`C:\Users\erikn` occurs in 146 documentation files, 43 tool files, eight
|
|
production-source files, two test files, and both root instruction files.
|
|
Production examples in `RetailCommandHelpTable`,
|
|
`RetailClientCommandCatalog`, `WeenieErrorMessages`, `OptionsPanelText`,
|
|
`ClientTextRefusals`, `AudioSettings`, `ConfigOptionsPageController`, and
|
|
`VendorUiController` cite a binary in the maintainer's Downloads directory.
|
|
Several comments also give a version or CodeView identity, which is the
|
|
durable evidence; the personal path adds no reproducible provenance and
|
|
implies access that another maintainer does not have.
|