From 350f805c853b063d14440468dfa7a5e5c13be44f Mon Sep 17 00:00:00 2001 From: Chao Wang <26245345+ChaoWao@users.noreply.github.com> Date: Tue, 28 Jul 2026 01:59:12 -0700 Subject: [PATCH] Add: codestyle rule on pto:: qualification in kernels Kernel sources carry two conventions. The collectives kernels qualify (pto::Stride<...>) and use no using-directive; the older scene-test kernels open with `using namespace pto;` and use bare names. Each is internally consistent, and nothing recorded which one new code should follow, so the split propagates by whichever file an author copied from. Rule 11 names qualification as the direction, because it is the only spelling that compiles whether or not a using-directive is in scope, and because a file-scope `using namespace` is what most style guides steer away from. New kernels qualify and do not add the directive; existing bare files are not defects and need no churn. The load-bearing part is the constraint that a file is qualified completely or not at all. Shape, Stride, Tile and GlobalTensor all live in namespace pto, so qualifying one and leaving its siblings bare yields adjacent lines that read worse than either consistent state. That is a real failure mode rather than a hypothetical: an earlier revision of PR #1547 rewrote Stride across 24 files and left Shape alone, and the resulting mixture is why it was reverted. A repo-wide sweep is ruled out with the measurement that rules it out: the 142 files carrying the directive hold roughly 3,200 bare uses, of which Tile alone is 2080. Rewriting them would touch every kernel, collide with every in-flight branch, and risk regex damage for no functional gain. Unifying the tree in one go needs its own decision plus a lint rule to hold the line. Co-Authored-By: Claude Opus 5 (1M context) --- .claude/rules/codestyle.md | 40 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/.claude/rules/codestyle.md b/.claude/rules/codestyle.md index beafaaf9d..7e959cfa3 100644 --- a/.claude/rules/codestyle.md +++ b/.claude/rules/codestyle.md @@ -157,3 +157,43 @@ Do **not** open a repo-wide mechanical rename PR: it collides with every in-flight branch, and a 6k-line diff cannot be reviewed for the handful of Tier-C names hiding in it. + +11. **Prefer `pto::`-qualified names in kernels; let the tree converge, never + sweep it.** Two conventions coexist in kernel sources today. The + collectives kernels qualify (`pto::Stride<…>`) and carry no + using-directive; the older scene-test kernels open with `using namespace + pto;` and use bare names. Both are internally consistent, so neither is a + defect on its own. + + **Qualification is the direction.** It is the only spelling that compiles + regardless of whether a using-directive is in scope, and a file-scope + `using namespace` is what most style guides steer away from. So: + + - **New kernels qualify, and do not add `using namespace pto;`.** Adding + the directive to a file that does not have it is a step backwards. + - **When you already edit a kernel, you may qualify it** — but see the + constraint below, which is not optional. + - **Existing files that use bare names are not defects.** Leave them + unless you have another reason to touch them. + + **The constraint: qualify a file completely or not at all.** `Shape`, + `Stride`, `Tile` and `GlobalTensor` all live in `namespace pto`, so + qualifying one of them and leaving its siblings bare produces adjacent + lines like + + ```cpp + using DynShapeDim5 = Shape<1, 1, 1, vRows, vCols>; + using DynStridDim5 = pto::Stride<1, 1, 1, kTCols_, 1>; + ``` + + which reads worse than either consistent state. A half-qualified file is + a defect where a fully bare one is not. + + **No repo-wide sweep.** As of 2026-07-28 the 142 files carrying `using + namespace pto;` contain roughly 3,200 bare uses — `Tile` 2080, + `GlobalTensor` 796, `Shape` 211, `Stride` 137. Rewriting them is a purely + stylistic change that would touch every kernel in the repo, collide with + every in-flight branch, and risk regex damage to member aliases and + comments for no functional gain. If the tree is ever to be unified in one + go, it needs its own decision plus a lint rule to hold the line — not a + hand-edited PR.