Skip to content

snapLambdaToGrid() carries 91 comment lines over 11 of code; claim corrections are additive #202

Open

Description

@gregfaletto

snapLambdaToGrid() (index.Rmd:2411, merged in #201) carries 91 ordinary comment lines
and 24 roxygen lines over 11 lines of code
in its body. Measured on origin/main:

git show origin/main:index.Rmd | awk 'NR>=2411 && NR<=2515' \
  | awk '{s=$0; sub(/^[ \t]+/,"",s); if(s ~ /^$/) b++; else if(s ~ /^#/) c++; else k++} \
         END{print "comment:",c," code:",k," blank:",b}'
# comment: 91  code: 11  blank: 3

This is not the repo's style — it is a recent change, and it has a mechanism.

The mechanism: corrections are additive

Every claim-correction commit on the #199 branch grew index.Rmd, despite each one
existing solely to fix prose that was already there:

3d4f2f4  Correct seven claims an unscoped audit found     +33/-20   net +13
feed33e  Drop the frac orientation the NEWS correction     +19/-11   net  +8
d46a431  Correct the claims the stage-8 passes found       +27/ -9   net +18
5ac1668  Narrow the claims the comment prose over-reached  +46/-31   net +15
dd7ef87  Correct two measured claims in the #199 block      +6/ -4   net  +2

Net +56 lines from five commits whose entire purpose was correcting prose. The pattern is
three lines out for one line in: the corrected claim, a sentence recording what the old one
said, and a directive telling the next editor not to write it again. Across the skill era, 13
of 36 commits changed zero code lines while net-adding comment lines.

The same pattern is measurable in fetwfePackage, where comment-to-code for added lines sat
in a 0.12–0.29 band for eighteen months and then went to 1.00 and 3.31 in the two months after
the shared development skill was adopted.

What has been fixed upstream

The skill now carries rules intended to stop the recurrence: no figure in a comment that no
test pins; a fact lives in one place and second copies cite rather than restate; no correction
history or editorial directives in shipped comments (git holds those); and a correction to a
comment may not lengthen it. This issue is about the sediment already merged here.

Suggested scope

snapLambdaToGrid()'s block should come down substantially. Candidates, in order:

  1. Correction history and editorial directives — e.g. the parenthetical instructing a
    future editor not to restate a claim as "the suite output is byte-identical with and
    without this line", and the clause saying a rule "must not be written as one". Git holds
    this.
  2. Unpinned figures — a 45 and a 1e-17 appear in comment prose with no test holding
    them. Pin the load-bearing ones and cite the pin; delete the rest.
  3. Restated facts — a term is defined around index.Rmd:2424 and contradicted around
    2491, 67 lines apart inside one function.

What should survive untouched is the actual rationale: why the code predicts at the penalty
glmnet fitted, and why the first formal is lambda_fitted rather than lambda_path.

litr note: all edits belong in index.Rmd; cssr/ is generated and a build discards
changes made there.

Not urgent, and no behavior is at risk — this is readability and future-correctness debt.

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

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions