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
 }