What is wrong
Comments, test names and one guide refer to the project's development history in words a reader cannot look up: "phase 12", "phase 15's spike, step 9", "the phase 12 plan", "spec phase 8", "a spike compiled …", "final review of phase 11, M3". To someone reading the library, these name nothing. They do not say what was measured, where, or why it matters, and the documents they once pointed at are not part of the library.
There are more than 80 such references (as of the head of #12). They appear in:
- public headers:
band.hpp, citation.hpp, constraint.hpp, error.hpp, lookup.hpp, measured.hpp, method.hpp, opaque.hpp, overlay.hpp, precision.hpp, quantity.hpp, rational.hpp, record.hpp, render.hpp, retry.hpp, rounding.hpp, sink.hpp, statistics.hpp, trace.hpp, trace_render.hpp;
- test names that show up in test output:
test/overflow_census_tests.cpp has "census: phase 13's fixtures" and "census: phase 12's cumulative sums and interpolation";
- test comments and section banners in
render_tests.cpp, trace_tests.cpp, trace_render_tests.cpp, document_tests.cpp, vocabulary_tests.cpp, record_*_tests.cpp and others, plus several test/negative/*.cpp;
- one guide,
docs/quantities.md:186 ("a spike compiled …");
cmake/CheckInstalledHeaders.cmake:7.
To find them all:
git grep -nE '\b[Pp]hase [0-9]+|\bspike\b|\bstep [0-9]+\)' -- include test examples tools docs/*.md README.md cmake CMakeLists.txt
Expected
Every comment states what it relies on in its own words. For example: "measured on cl 19.51 and g++-14: the five-parameter spelling compiles", not "measured by phase 14's spike". A reference that adds nothing is dropped. Test names say what they test. Section banners name the feature, not the phase that added it.
The design documents under docs/superpowers/ record how the work was planned, and are out of scope.
Notes
- Some comments quote a measurement as their evidence, for example "
record.hpp: all the same -- measured by phase 14's spike on cl, clang-cl, …". Keep the measurement and drop the label, or point at the test that pins it where one exists.
- Renaming the two census test cases is safe: no build file refers to their names.
What is wrong
Comments, test names and one guide refer to the project's development history in words a reader cannot look up: "phase 12", "phase 15's spike, step 9", "the phase 12 plan", "spec phase 8", "a spike compiled …", "final review of phase 11, M3". To someone reading the library, these name nothing. They do not say what was measured, where, or why it matters, and the documents they once pointed at are not part of the library.
There are more than 80 such references (as of the head of #12). They appear in:
band.hpp,citation.hpp,constraint.hpp,error.hpp,lookup.hpp,measured.hpp,method.hpp,opaque.hpp,overlay.hpp,precision.hpp,quantity.hpp,rational.hpp,record.hpp,render.hpp,retry.hpp,rounding.hpp,sink.hpp,statistics.hpp,trace.hpp,trace_render.hpp;test/overflow_census_tests.cpphas"census: phase 13's fixtures"and"census: phase 12's cumulative sums and interpolation";render_tests.cpp,trace_tests.cpp,trace_render_tests.cpp,document_tests.cpp,vocabulary_tests.cpp,record_*_tests.cppand others, plus severaltest/negative/*.cpp;docs/quantities.md:186("a spike compiled …");cmake/CheckInstalledHeaders.cmake:7.To find them all:
Expected
Every comment states what it relies on in its own words. For example: "measured on cl 19.51 and g++-14: the five-parameter spelling compiles", not "measured by phase 14's spike". A reference that adds nothing is dropped. Test names say what they test. Section banners name the feature, not the phase that added it.
The design documents under
docs/superpowers/record how the work was planned, and are out of scope.Notes
record.hpp: all the same -- measured by phase 14's spike on cl, clang-cl, …". Keep the measurement and drop the label, or point at the test that pins it where one exists.