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/cli/migrate/common.go

@@ -59,12 +59,12 @@ func openMigrator(
 		return nil, nil, err
 	}
 
-	m, err := store.NewMigrator(db)
+	migrator, err := store.NewMigrator(db)
 	if err != nil {
 		return nil, nil, errors.Join(err, db.Close())
 	}
 
-	return m, db, nil
+	return migrator, db, nil
 }
 
 // closeDB closes db when deferred, adding any error to *err.
@@ -80,61 +80,72 @@ type errWriter struct {
 }
 
 // printf writes like fmt.Fprintf, unless an earlier write failed.
-func (e *errWriter) printf(format string, a ...any) {
+func (e *errWriter) printf(format string, args ...any) {
 	if e.err == nil {
-		_, e.err = fmt.Fprintf(e.w, format, a...)
+		_, e.err = fmt.Fprintf(e.w, format, args...)
 	}
 }
 
 // printResults lists migrations that ran, e.g.
 //
 //	applied   00003_create_release_tags_table.sql  (2ms)
-func printResults(w io.Writer, results []*goose.MigrationResult) error {
-	ew := &errWriter{w: w}
-	for _, r := range results {
+func printResults(out io.Writer, results []*goose.MigrationResult) error {
+	output := &errWriter{
+		w: out,
+	}
+	for _, result := range results {
 		verb := "applied"
-		if r.Direction == "down" {
+		if result.Direction == "down" {
 			verb = "reverted"
 		}
-		ew.printf("  %-9s %s  (%s)\n",
-			verb, filepath.Base(r.Source.Path), r.Duration.Round(time.Millisecond))
+		output.printf(
+			"  %-9s %s  (%s)\n",
+			verb,
+			filepath.Base(result.Source.Path),
+			result.Duration.Round(time.Millisecond),
+		)
 	}
-	return ew.err
+	return output.err
 }
 
 // failure prints what ran before a failed migration and describes the
 // failure. Each migration runs in a transaction, so the failed one has been
 // rolled back and the database is at the last version that succeeded.
-func failure(w io.Writer, err error) error {
-	var pe *goose.PartialError
-	if !errors.As(err, &pe) {
+func failure(out io.Writer, err error) error {
+	var partialErr *goose.PartialError
+	if !errors.As(err, &partialErr) {
 		return err
 	}
 
-	printErr := printResults(w, pe.Applied)
+	printErr := printResults(out, partialErr.Applied)
 
 	name := "unknown migration"
-	if pe.Failed != nil && pe.Failed.Source != nil {
-		name = filepath.Base(pe.Failed.Source.Path)
+	if partialErr.Failed != nil && partialErr.Failed.Source != nil {
+		name = filepath.Base(partialErr.Failed.Source.Path)
 	}
 
-	return errors.Join(fmt.Errorf(
-		"migration %s failed and was rolled back; the database is at the last "+
-			"version that succeeded.\nMigration error: %w",
-		name, pe.Err), printErr)
+	return errors.Join(
+		fmt.Errorf(
+			"migration %s failed and was rolled back; the database is at the last "+
+				"version that succeeded.\nMigration error: %w",
+			name,
+			partialErr.Err,
+		),
+		printErr,
+	)
 }
 
 // printVersion reports where the database ended up.
-func printVersion(ctx context.Context, w io.Writer, m *goose.Provider) error {
-	v, err := m.GetDBVersion(ctx)
+func printVersion(ctx context.Context, out io.Writer, migrator *goose.Provider) error {
+	dbVersion, err := migrator.GetDBVersion(ctx)
 	if err != nil {
 		return err
 	}
 
-	if v == 0 {
-		_, err = fmt.Fprintln(w, "Database cleared")
+	if dbVersion == 0 {
+		_, err = fmt.Fprintln(out, "Database cleared")
 	} else {
-		_, err = fmt.Fprintf(w, "Database migrated to version %d\n", v)
+		_, err = fmt.Fprintf(out, "Database migrated to version %d\n", dbVersion)
 	}
 	return err
 }

internal/cli/migrate/common_test.go

@@ -16,7 +16,9 @@ import (
 
 func result(path, direction string) *goose.MigrationResult {
 	return &goose.MigrationResult{
-		Source:    &goose.Source{Path: "migrations/" + path},
+		Source: &goose.Source{
+			Path: "migrations/" + path,
+		},
 		Direction: direction,
 		Duration:  1500 * time.Microsecond,
 	}
@@ -45,7 +47,9 @@ func TestFailurePartial(t *testing.T) {
 }
 
 func TestFailureWithoutFailedSource(t *testing.T) {
-	err := failure(&bytes.Buffer{}, &goose.PartialError{Err: errors.New("boom")})
+	err := failure(&bytes.Buffer{}, &goose.PartialError{
+		Err: errors.New("boom"),
+	})
 	if err == nil || !strings.Contains(err.Error(), "unknown migration") {
 		t.Errorf("err = %v, want unknown migration", err)
 	}

internal/cli/migrate/down.go

@@ -32,13 +32,13 @@ confirmed by providing -yes.`,
 			yes, _ := cmd.Flags().GetBool("yes")
 			steps, _ := cmd.Flags().GetUint("steps")
 
-			m, db, err := openMigrator(cmd, opts, false, false)
+			migrator, db, err := openMigrator(cmd, opts, false, false)
 			if err != nil {
 				return err
 			}
 			defer closeDB(db, &err)
 
-			results, err := store.StepDown(cmd.Context(), m, int(steps), yes)
+			results, err := store.StepDown(cmd.Context(), migrator, int(steps), yes)
 
 			if len(results) == 0 && err == nil {
 				fmt.Println("No changes made to database (empty)")
@@ -58,7 +58,7 @@ confirmed by providing -yes.`,
 				return failure(cmd.OutOrStdout(), err)
 			}
 
-			return printVersion(cmd.Context(), cmd.OutOrStdout(), m)
+			return printVersion(cmd.Context(), cmd.OutOrStdout(), migrator)
 		},
 	}
 	cmd.Flags().Uint(

internal/cli/migrate/migrate_test.go

@@ -55,7 +55,9 @@ func TestMigrateUpCreateThenStatus(t *testing.T) {
 	latest := latestVersion(t)
 
 	out := mustRun(t, "migrate", "up", "--create")
-	cmdtest.Contains(t, out,
+	cmdtest.Contains(
+		t,
+		out,
 		"applied   00001_create_opportunities_table.sql",
 		fmt.Sprintf("Database migrated to version %d", latest),
 	)
@@ -64,7 +66,9 @@ func TestMigrateUpCreateThenStatus(t *testing.T) {
 	}
 
 	out = mustRun(t, "migrate", "status")
-	cmdtest.Contains(t, out,
+	cmdtest.Contains(
+		t,
+		out,
 		fmt.Sprintf("Database version %d of %d (up-to-date)", latest, latest),
 		"00001_create_opportunities_table.sql",
 	)
@@ -87,8 +91,11 @@ func TestMigrateUpAsksBeforeCreating(t *testing.T) {
 
 	out, err := run(t, "n\n", "migrate", "up")
 	cmdtest.ErrContains(t, err, "no database file")
-	cmdtest.Contains(t, out,
-		"Database file './test.db' does not exist. Would you like to create it?")
+	cmdtest.Contains(
+		t,
+		out,
+		"Database file './test.db' does not exist. Would you like to create it?",
+	)
 	if cmdtest.Exists("test.db") {
 		t.Error("test.db was created after answering no")
 	}
@@ -110,8 +117,11 @@ func TestMigrateUpBySteps(t *testing.T) {
 	cmdtest.Contains(t, out, "Database migrated to version 2")
 
 	out = mustRun(t, "migrate", "status")
-	cmdtest.Contains(t, out,
-		fmt.Sprintf("Database version 2 of %d (%d pending)", latest, latest-2))
+	cmdtest.Contains(
+		t,
+		out,
+		fmt.Sprintf("Database version 2 of %d (%d pending)", latest, latest-2),
+	)
 }
 
 func TestMigrateDown(t *testing.T) {
@@ -130,8 +140,11 @@ func TestMigrateDown(t *testing.T) {
 		_, err := run(t, "", args...)
 		cmdtest.ErrContains(t, err, "pass the --yes flag")
 	}
-	cmdtest.Contains(t, mustRun(t, "migrate", "status"),
-		fmt.Sprintf("Database version %d of %d", latest-1, latest))
+	cmdtest.Contains(
+		t,
+		mustRun(t, "migrate", "status"),
+		fmt.Sprintf("Database version %d of %d", latest-1, latest),
+	)
 
 	out = mustRun(t, "migrate", "down", "--steps", "0", "--yes")
 	cmdtest.Contains(t, out, "Database cleared")

internal/cli/migrate/status.go

@@ -22,51 +22,63 @@ import (
 //	  1  applied  2026-10-07 10:12:01  00001_create_opportunities_table.sql
 //	  ...
 //	  5  pending                       00005_create_opportunity_classifications_table.sql
-func printStatus(ctx context.Context, w io.Writer, m *goose.Provider) error {
-	statuses, err := m.Status(ctx)
+func printStatus(ctx context.Context, out io.Writer, migrator *goose.Provider) error {
+	statuses, err := migrator.Status(ctx)
 	if err != nil {
 		return err
 	}
 
-	current, err := m.GetDBVersion(ctx)
+	current, err := migrator.GetDBVersion(ctx)
 	if err != nil {
 		return err
 	}
 
-	latest := store.LatestVersion(m)
+	latest := store.LatestVersion(migrator)
 
 	pending := 0
-	for _, s := range statuses {
-		if s.State == goose.StatePending {
+	for _, status := range statuses {
+		if status.State == goose.StatePending {
 			pending++
 		}
 	}
 
-	ew := &errWriter{w: w}
+	output := &errWriter{
+		w: out,
+	}
 	switch {
 	case current > latest:
-		ew.printf("Database version %d is newer than this build (latest %d)\n",
-			current, latest)
+		output.printf(
+			"Database version %d is newer than this build (latest %d)\n",
+			current,
+			latest,
+		)
 	case pending == 0:
-		ew.printf("Database version %d of %d (up-to-date)\n", current, latest)
+		output.printf("Database version %d of %d (up-to-date)\n", current, latest)
 	default:
-		ew.printf("Database version %d of %d (%d pending)\n", current, latest, pending)
+		output.printf("Database version %d of %d (%d pending)\n", current, latest, pending)
 	}
-	if ew.err != nil {
-		return ew.err
+	if output.err != nil {
+		return output.err
 	}
 
-	tw := tabwriter.NewWriter(w, 0, 0, 2, ' ', 0)
-	ew = &errWriter{w: tw}
-	for _, s := range statuses {
-		applied := ""
-		if s.State == goose.StateApplied {
-			applied = s.AppliedAt.Local().Format("2006-01-02 15:04:05")
-		}
-		ew.printf("  %d\t%s\t%s\t%s\n",
-			s.Source.Version, s.State, applied, filepath.Base(s.Source.Path))
+	table := tabwriter.NewWriter(out, 0, 0, 2, ' ', 0)
+	output = &errWriter{
+		w: table,
 	}
-	return errors.Join(ew.err, tw.Flush())
+	for _, status := range statuses {
+		applied := ""
+		if status.State == goose.StateApplied {
+			applied = status.AppliedAt.Local().Format("2006-01-02 15:04:05")
+		}
+		output.printf(
+			"  %d\t%s\t%s\t%s\n",
+			status.Source.Version,
+			status.State,
+			applied,
+			filepath.Base(status.Source.Path),
+		)
+	}
+	return errors.Join(output.err, table.Flush())
 }
 
 func commandStatus(opts *cli.Options) *cobra.Command {
@@ -83,13 +95,13 @@ func commandStatus(opts *cli.Options) *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) (err error) {
 			slog.Debug("command run", "command", "migrate.status")
 
-			m, db, err := openMigrator(cmd, opts, false, false)
+			migrator, db, err := openMigrator(cmd, opts, false, false)
 			if err != nil {
 				return err
 			}
 			defer closeDB(db, &err)
 
-			return printStatus(cmd.Context(), cmd.OutOrStdout(), m)
+			return printStatus(cmd.Context(), cmd.OutOrStdout(), migrator)
 		},
 	}
 }

internal/cli/migrate/up.go

@@ -16,13 +16,13 @@ import (
 func runStepUp(
 	cmd *cobra.Command, opts *cli.Options, steps int, create bool,
 ) (err error) {
-	m, db, err := openMigrator(cmd, opts, true, create)
+	migrator, db, err := openMigrator(cmd, opts, true, create)
 	if err != nil {
 		return err
 	}
 	defer closeDB(db, &err)
 
-	results, err := store.StepUp(cmd.Context(), m, int(steps))
+	results, err := store.StepUp(cmd.Context(), migrator, int(steps))
 
 	if len(results) == 0 && err == nil {
 		_, err := fmt.Fprintln(cmd.OutOrStdout(), "No changes made to database (up-to-date)")
@@ -37,7 +37,7 @@ func runStepUp(
 		return failure(cmd.OutOrStdout(), err)
 	}
 
-	return printVersion(cmd.Context(), cmd.OutOrStdout(), m)
+	return printVersion(cmd.Context(), cmd.OutOrStdout(), migrator)
 }
 
 func commandUp(opts *cli.Options) *cobra.Command {