From bddbd74e4a73e8e32bcf648efd1cac5655f6d0cd Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Thu, 17 Sep 2026 12:11:42 +0200 Subject: comments that explain the code, not how it was written About 340 comments cited the development process: task and plan numbers, fix waves, rulings, reviewers, and the author in the third person with a date. None of that exists outside the work itself, so to a reader it pointed at nothing. Each one now states the engineering reason it was standing in front of; where a comment was provenance and nothing else, it is gone. References to docs/design.md and docs/gui-design.md by section stay: both ship with the repository. The design documents lose their amendment diaries - CHANGELOG.md is that record - and the GUI's says plainly that the window has gone further than the document. Only comments changed. Every .go file was parsed and its code printed with comments stripped, before and after: the two hashes are identical across all 175 files. --- gui/internal/model/filter.go | 3 +-- gui/internal/model/highlight.go | 2 +- gui/internal/model/newdir.go | 3 +-- gui/internal/model/plan.go | 7 +++---- gui/internal/model/plan_test.go | 5 ++--- gui/internal/model/prefs.go | 4 ++-- gui/internal/model/preview.go | 7 +++---- gui/internal/model/preview_test.go | 7 +++---- gui/internal/model/rules_test.go | 4 ++-- gui/internal/model/sort.go | 2 +- gui/internal/model/testrule_test.go | 2 +- 11 files changed, 20 insertions(+), 26 deletions(-) (limited to 'gui/internal/model') diff --git a/gui/internal/model/filter.go b/gui/internal/model/filter.go index af617c3..b9844cf 100644 --- a/gui/internal/model/filter.go +++ b/gui/internal/model/filter.go @@ -11,8 +11,7 @@ import ( // FuzzyMatch reports whether every character of pattern appears in text in // order - the way fzf matches - and how good the match is. Capitals and // accents are ignored, using krino's own folding, so "zazolc" finds -// "zażółć" exactly as a rule with (fold yes) would (his request, -// 2026-09-17). +// "zażółć" exactly as a rule with (fold yes) would. // // The score rewards characters that follow one another and those at the // start of a word, so "lec" ranks "lectio-2026.pdf" above diff --git a/gui/internal/model/highlight.go b/gui/internal/model/highlight.go index e34d9d9..55742ef 100644 --- a/gui/internal/model/highlight.go +++ b/gui/internal/model/highlight.go @@ -29,7 +29,7 @@ var actionHeads = map[string]bool{ // string comments out the rest of its line; a string runs to its closing // quote, a backslash escaping the next character; the first symbol after // "(" is the form's head. Nothing here knows about widgets, so the rules of -// the little language stay testable (his request, 2026-09-16). +// the little language stay testable. func Spans(text string) []Span { var out []Span runes := []rune(text) diff --git a/gui/internal/model/newdir.go b/gui/internal/model/newdir.go index d0df6db..f65763c 100644 --- a/gui/internal/model/newdir.go +++ b/gui/internal/model/newdir.go @@ -10,8 +10,7 @@ import ( // AddDirectory writes dirs/NAME.conf from the template with path filled in // and adds NAME to krino.conf's include - exactly what `krino new NAME // PATH` does, through the same code, so a directory made in the window is -// indistinguishable from one made on the command line (his report that the -// window had no way to add one, 2026-09-17). +// indistinguishable from one made on the command line. // // It returns the new file's path. The caller reloads the engine: until it // does, the window knows nothing of the new directory. diff --git a/gui/internal/model/plan.go b/gui/internal/model/plan.go index 7c24991..12b0d13 100644 --- a/gui/internal/model/plan.go +++ b/gui/internal/model/plan.go @@ -240,8 +240,7 @@ func (t *PlanTab) Replace(i int, kind plan.Kind) error { // ReplaceSelected swaps the steps of every checked file for the one action // chosen - "Trash the checked files", "Delete them permanently" - and // reports how many were changed. Nothing happens on disk: like every other -// review decision, it changes the plan, and Apply carries it out (his -// request, 2026-09-17). +// review decision, it changes the plan, and Apply carries it out. func (t *PlanTab) ReplaceSelected(kind plan.Kind) (int, error) { n := 0 for i, r := range t.Rows { @@ -261,7 +260,7 @@ func (t *PlanTab) ReplaceSelected(kind plan.Kind) (int, error) { // the Trash, where krino undo can still reach it. It is a review decision, // like trashing a file by hand, so the rule that a duplicate is never // deleted - which binds rules, not the person reading the plan - does not -// stand in its way (his request, 2026-09-17). +// stand in its way. func (t *PlanTab) KeepThisCopy(i int) error { if i < 0 || i >= len(t.Rows) { return fmt.Errorf("model: no row %d", i) @@ -339,7 +338,7 @@ func (t *PlanTab) record(res *engine.ApplyResult) { // AgeText is how long ago a file was last written, in the units krino's own // (age ...) test uses: minutes, hours, days and weeks, and years past that, -// so a plan can be read at a glance (his request, 2026-09-17). +// so a plan can be read at a glance. func AgeText(mod time.Time, now time.Time) string { if mod.IsZero() { return "" diff --git a/gui/internal/model/plan_test.go b/gui/internal/model/plan_test.go index 0aa0361..8873e55 100644 --- a/gui/internal/model/plan_test.go +++ b/gui/internal/model/plan_test.go @@ -315,8 +315,7 @@ func equal(a, b []string) bool { } // TestReplaceSelected: one choice for every checked file at once - trash -// them, or delete them - changing the plan and nothing on disk until Apply -// (his request, 2026-09-17). +// them, or delete them - changing the plan and nothing on disk until Apply. func TestReplaceSelected(t *testing.T) { conf := "(path \"~/dl\")\n(rule \"all\" (move \"Out\"))\n" e, h := sandboxDir(t, conf, map[string]string{"a.pdf": "one", "b.pdf": "two", "c.pdf": "three"}) @@ -411,7 +410,7 @@ func TestAgeText(t *testing.T) { // TestKeepThisCopy: choosing the downloaded copy over the filed one puts it // in the other's place and sends the other to the Trash, where undo can -// still reach it (his request, 2026-09-17). +// still reach it. func TestKeepThisCopy(t *testing.T) { conf := "(path \"~/dl\")\n(rule \"dupes\" (when (duplicate \"~/docs\")) (move \"Dupes\"))\n" e, h := sandboxDir(t, conf, map[string]string{"report.pdf": "the same bytes"}) diff --git a/gui/internal/model/prefs.go b/gui/internal/model/prefs.go index 2d2dc04..4b70de3 100644 --- a/gui/internal/model/prefs.go +++ b/gui/internal/model/prefs.go @@ -12,7 +12,7 @@ import ( // Prefs is how the window behaves - nothing about what krino does to // files, which belongs in the configuration. It lives beside krino.conf as -// gui.json, a file krino itself never reads (his request, 2026-09-16). +// gui.json, a file krino itself never reads. type Prefs struct { // Colours paints the configuration in the Text tab. Colours bool `json:"colours"` @@ -28,7 +28,7 @@ type Prefs struct { PreviewWidth int `json:"preview_width"` // ListWidth and ListHeight are where the divider between the file list // and the explanation was left, in each layout. Every divider a hand - // moves is kept (his request, 2026-09-17). + // moves is kept. ListWidth int `json:"list_width"` ListHeight int `json:"list_height"` // ShowSize, ShowAge and ShowRule are the columns that can be turned off diff --git a/gui/internal/model/preview.go b/gui/internal/model/preview.go index a180dff..f8bf75d 100644 --- a/gui/internal/model/preview.go +++ b/gui/internal/model/preview.go @@ -25,7 +25,7 @@ const ( ) // Preview is what to show of a file beside its explanation: a picture, some -// of its text, or nothing with the reason (his request, 2026-09-16). +// of its text, or nothing with the reason. type Preview struct { Kind PreviewKind Image string // a file to show: the file itself, or a rendered page @@ -82,9 +82,8 @@ func MakePreview(ctx context.Context, path, tmp string, px int) Preview { // // Each render goes in a directory of its own. pdftoppm names its output // after the page number, so a shared directory would hold several files -// called page-1.png and the wrong one could be picked up - which is what -// happened: a preview showed the page of a PDF looked at earlier (his -// report, 2026-09-17). +// called page-1.png and the wrong one could be picked up - a preview could +// show the page of a PDF looked at earlier. func pdfPreview(ctx context.Context, path, tmp string, sz int64, px int) Preview { if _, err := exec.LookPath("pdftoppm"); err == nil { dir, err := os.MkdirTemp(tmp, "page-") diff --git a/gui/internal/model/preview_test.go b/gui/internal/model/preview_test.go index 388ff7b..f310386 100644 --- a/gui/internal/model/preview_test.go +++ b/gui/internal/model/preview_test.go @@ -100,8 +100,8 @@ func TestPreviewShowsOnlyTheHead(t *testing.T) { // TestPdfPreviewsDoNotMixUp: two PDFs looked at one after the other each // get their own rendered page. pdftoppm names its file after the page -// number, so previews sharing a directory would collide - one of his ended -// up showing another document's cover. +// number, so previews sharing a directory would collide, one showing +// another document's cover. func TestPdfPreviewsDoNotMixUp(t *testing.T) { if _, err := exec.LookPath("pdftoppm"); err != nil { t.Skip("pdftoppm is not installed") @@ -168,8 +168,7 @@ func pngSize(t *testing.T, path string) (w, h int) { } // TestPreviewRendersToTheSizeAsked: a taller preview gets a larger page, so -// dragging the pane open does not just magnify a small render (his request, -// 2026-09-17). +// dragging the pane open does not just magnify a small render. func TestPreviewRendersToTheSizeAsked(t *testing.T) { if _, err := exec.LookPath("pdftoppm"); err != nil { t.Skip("pdftoppm is not installed") diff --git a/gui/internal/model/rules_test.go b/gui/internal/model/rules_test.go index c7fa384..c8ee212 100644 --- a/gui/internal/model/rules_test.go +++ b/gui/internal/model/rules_test.go @@ -34,8 +34,8 @@ func TestOpenAndCheck(t *testing.T) { t.Error("an untouched file counts as modified") } - // An unknown placeholder is refused at check time (plan 12 task 3), and - // the position is the action's, inside this file. + // An unknown placeholder is refused at check time, and the position is + // the action's, inside this file. r.SetText("(path \"~/dl\")\n(rule \"all\" (move \"Out/{nope}\"))\n") if !r.Modified() { t.Error("edited text does not count as modified") diff --git a/gui/internal/model/sort.go b/gui/internal/model/sort.go index 9968a08..1918576 100644 --- a/gui/internal/model/sort.go +++ b/gui/internal/model/sort.go @@ -9,7 +9,7 @@ import ( // The orders a plan can be read in. "default" is the order krino planned // the directory in, which is the order the files were scanned; the rest are -// what a column is worth sorting by (his request, 2026-09-17). +// what a column is worth sorting by. const ( SortDefault = "default" SortName = "name" diff --git a/gui/internal/model/testrule_test.go b/gui/internal/model/testrule_test.go index 99989f4..8e64a32 100644 --- a/gui/internal/model/testrule_test.go +++ b/gui/internal/model/testrule_test.go @@ -10,7 +10,7 @@ import ( // TestTestRule: testing one rule says which of the directory's files it // would act on, and what would happen to each - answered from the unsaved -// text, and changing nothing (GUI design §5.3, his request 2026-09-16). +// text, and changing nothing (GUI design §5.3). func TestTestRule(t *testing.T) { conf := "(path \"~/dl\")\n" + "(rule \"pdfs\" (when (type pdf)) (move \"Docs\") (stop))\n" + -- cgit v1.3