Naming, layout and comments: descriptive full-word names, one item per line in wrapped calls and literals, and doc comments on exported names

Short and single-letter names in application code become full words (tests
keep theirs). Wrapped calls, signatures and composite literals put one item
per line, and one-line function bodies are expanded. Exported names and
groups of constants get doc comments, and comments refer to the renamed
identifiers.

internal/util/bytesize.go

@@ -24,33 +24,75 @@ var byteUnits = []struct {
 	name string
 	size int64
 }{
-	{"EiB", humanize.EiByte}, {"EB", humanize.EByte},
-	{"PiB", humanize.PiByte}, {"PB", humanize.PByte},
-	{"TiB", humanize.TiByte}, {"TB", humanize.TByte},
-	{"GiB", humanize.GiByte}, {"GB", humanize.GByte},
-	{"MiB", humanize.MiByte}, {"MB", humanize.MByte},
-	{"KiB", humanize.KiByte}, {"KB", humanize.KByte},
+	{
+		name: "EiB",
+		size: humanize.EiByte,
+	},
+	{
+		name: "EB",
+		size: humanize.EByte,
+	},
+	{
+		name: "PiB",
+		size: humanize.PiByte,
+	},
+	{
+		name: "PB",
+		size: humanize.PByte,
+	},
+	{
+		name: "TiB",
+		size: humanize.TiByte,
+	},
+	{
+		name: "TB",
+		size: humanize.TByte,
+	},
+	{
+		name: "GiB",
+		size: humanize.GiByte,
+	},
+	{
+		name: "GB",
+		size: humanize.GByte,
+	},
+	{
+		name: "MiB",
+		size: humanize.MiByte,
+	},
+	{
+		name: "MB",
+		size: humanize.MByte,
+	},
+	{
+		name: "KiB",
+		size: humanize.KiByte,
+	},
+	{
+		name: "KB",
+		size: humanize.KByte,
+	},
 }
 
 // ParseByteSize parses a size such as "32KiB", "1 MB" or "4096". Unit names
 // are case-insensitive. "-1" (or "-1B") is ByteSizeNoLimit; any other
 // negative size is an error.
-func ParseByteSize(s string) (ByteSize, error) {
-	trimmed := strings.TrimSpace(s)
+func ParseByteSize(text string) (ByteSize, error) {
+	trimmed := strings.TrimSpace(text)
 	if trimmed == "-1" || strings.EqualFold(trimmed, "-1B") {
 		return ByteSizeNoLimit, nil
 	}
 	if strings.HasPrefix(trimmed, "-") {
-		return 0, fmt.Errorf("byte size %q is negative; only -1 (no limit) is allowed", s)
+		return 0, fmt.Errorf("byte size %q is negative; only -1 (no limit) is allowed", text)
 	}
-	n, err := humanize.ParseBytes(s)
+	parsed, err := humanize.ParseBytes(text)
 	if err != nil {
 		return 0, err
 	}
-	if n > math.MaxInt64 {
-		return 0, fmt.Errorf("byte size %q is too large", s)
+	if parsed > math.MaxInt64 {
+		return 0, fmt.Errorf("byte size %q is too large", text)
 	}
-	return ByteSize(n), nil
+	return ByteSize(parsed), nil
 }
 
 // String formats b exactly, in the largest unit that divides it (e.g. "32KiB",
@@ -61,9 +103,9 @@ func (b ByteSize) String() string {
 		return "-1"
 	}
 	if b != 0 {
-		for _, u := range byteUnits {
-			if int64(b)%u.size == 0 {
-				return strconv.FormatInt(int64(b)/u.size, 10) + u.name
+		for _, unit := range byteUnits {
+			if int64(b)%unit.size == 0 {
+				return strconv.FormatInt(int64(b)/unit.size, 10) + unit.name
 			}
 		}
 	}

internal/util/worker.go

@@ -135,26 +135,29 @@ func (w Worker) execute(
 	}
 }
 
-// AwaitTask runs fn in its own goroutine and returns its result, or ctx.Err()
+// AwaitTask runs task in its own goroutine and returns its result, or ctx.Err()
 // if ctx is cancelled first. This lets a Task stop waiting on a call that does
 // not respond promptly to cancellation.
 //
 // The result channel is buffered, so if ctx wins the race the goroutine can
 // still deliver its result and exit instead of blocking forever.
-func AwaitTask[T any](ctx context.Context, fn func() (T, error)) (T, error) {
+func AwaitTask[T any](ctx context.Context, task func() (T, error)) (T, error) {
 	type result struct {
 		val T
 		err error
 	}
-	ch := make(chan result, 1)
+	results := make(chan result, 1)
 	go func() {
-		val, err := fn()
-		ch <- result{val, err}
+		value, err := task()
+		results <- result{
+			val: value,
+			err: err,
+		}
 	}()
 
 	select {
-	case r := <-ch:
-		return r.val, r.err
+	case result := <-results:
+		return result.val, result.err
 	case <-ctx.Done():
 		var zero T
 		return zero, ctx.Err()
@@ -162,15 +165,15 @@ func AwaitTask[T any](ctx context.Context, fn func() (T, error)) (T, error) {
 }
 
 // AwaitTaskE is AwaitTask for a function that returns only an error.
-func AwaitTaskE(ctx context.Context, fn func() error) error {
-	ch := make(chan error, 1)
+func AwaitTaskE(ctx context.Context, task func() error) error {
+	results := make(chan error, 1)
 	go func() {
-		err := fn()
-		ch <- err
+		err := task()
+		results <- err
 	}()
 
 	select {
-	case err := <-ch:
+	case err := <-results:
 		return err
 	case <-ctx.Done():
 		return ctx.Err()

internal/util/worker_test.go

@@ -19,14 +19,26 @@ func TestMain(m *testing.M) {
 }
 
 func TestWorkerRunRejectsBadConfig(t *testing.T) {
-	noop := func(context.Context, time.Time) error { return nil }
+	noop := func(context.Context, time.Time) error {
+		return nil
+	}
 	tests := []struct {
 		name string
 		w    Worker
 	}{
-		{"no task", Worker{Name: "a", Interval: time.Second}},
-		{"zero interval", Worker{Name: "b", Task: noop}},
-		{"negative interval", Worker{Name: "c", Interval: -time.Second, Task: noop}},
+		{"no task", Worker{
+			Name:     "a",
+			Interval: time.Second,
+		}},
+		{"zero interval", Worker{
+			Name: "b",
+			Task: noop,
+		}},
+		{"negative interval", Worker{
+			Name:     "c",
+			Interval: -time.Second,
+			Task:     noop,
+		}},
 	}
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
@@ -90,7 +102,9 @@ func TestWorkerRunCheckpoints(t *testing.T) {
 	}
 
 	done := make(chan error, 1)
-	go func() { done <- w.Run(ctx, since0) }()
+	go func() {
+		done <- w.Run(ctx, since0)
+	}()
 	select {
 	case err := <-done:
 		if err != nil {
@@ -186,7 +200,11 @@ func TestWorkerExecute(t *testing.T) {
 	}
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
-			w := Worker{Task: func(context.Context, time.Time) error { return tc.err }}
+			w := Worker{
+				Task: func(context.Context, time.Time) error {
+					return tc.err
+				},
+			}
 			before := time.Now()
 			got := w.execute(context.Background(), logger, since)
 			if tc.advance {
@@ -202,11 +220,15 @@ func TestWorkerExecute(t *testing.T) {
 
 func TestAwaitTask(t *testing.T) {
 	errFail := errors.New("boom")
-	v, err := AwaitTask(context.Background(), func() (int, error) { return 42, nil })
+	v, err := AwaitTask(context.Background(), func() (int, error) {
+		return 42, nil
+	})
 	if v != 42 || err != nil {
 		t.Fatalf("got (%d, %v), want (42, nil)", v, err)
 	}
-	v, err = AwaitTask(context.Background(), func() (int, error) { return 7, errFail })
+	v, err = AwaitTask(context.Background(), func() (int, error) {
+		return 7, errFail
+	})
 	if v != 7 || !errors.Is(err, errFail) {
 		t.Fatalf("got (%d, %v), want (7, %v)", v, err, errFail)
 	}
@@ -214,8 +236,14 @@ func TestAwaitTask(t *testing.T) {
 	ctx, cancel := context.WithCancel(context.Background())
 	release := make(chan struct{})
 	defer close(release)
-	go func() { time.Sleep(5 * time.Millisecond); cancel() }()
-	v, err = AwaitTask(ctx, func() (int, error) { <-release; return 1, nil })
+	go func() {
+		time.Sleep(5 * time.Millisecond)
+		cancel()
+	}()
+	v, err = AwaitTask(ctx, func() (int, error) {
+		<-release
+		return 1, nil
+	})
 	if v != 0 || !errors.Is(err, context.Canceled) {
 		t.Fatalf("got (%d, %v), want (0, context.Canceled)", v, err)
 	}
@@ -223,12 +251,16 @@ func TestAwaitTask(t *testing.T) {
 
 func TestAwaitTaskE(t *testing.T) {
 	errFail := errors.New("boom")
-	if err := AwaitTaskE(context.Background(), func() error { return nil }); err != nil {
+	if err := AwaitTaskE(context.Background(), func() error {
+		return nil
+	}); err != nil {
 		t.Fatal(err)
 	}
 	if err := AwaitTaskE(
 		context.Background(),
-		func() error { return errFail },
+		func() error {
+			return errFail
+		},
 	); !errors.Is(
 		err,
 		errFail,
@@ -242,7 +274,10 @@ func TestAwaitTaskE(t *testing.T) {
 	defer close(release)
 	if err := AwaitTaskE(
 		ctx,
-		func() error { <-release; return nil },
+		func() error {
+			<-release
+			return nil
+		},
 	); !errors.Is(
 		err,
 		context.DeadlineExceeded,