Skip to content

Replace internal development labels ("phase N", "spike") in headers, tests and docs with self-describing text #13

Description

@christianparpart

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions