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/store/store.go

@@ -103,57 +103,57 @@ func (f OpportunityFilter) limit() int {
 	return f.Limit
 }
 
-// prepareOpportunity validates t and normalises it in place before saving: child
-// rows get the opportunity's UUID and their release id, times are converted to
-// UTC (so stored timestamps compare correctly as text), and
+// prepareOpportunity validates opportunity and normalises it in place before
+// saving: child rows get the opportunity's UUID and their release id, times
+// are converted to UTC (so stored timestamps compare correctly as text), and
 // LatestReleaseDate becomes the newest release date in the save.
-func prepareOpportunity(t *types.Opportunity) error {
-	if t == nil {
+func prepareOpportunity(opportunity *types.Opportunity) error {
+	if opportunity == nil {
 		return errors.New("store: nil opportunity")
 	}
-	if t.UUID == "" {
+	if opportunity.UUID == "" {
 		return errors.New("store: opportunity has no UUID")
 	}
 
-	t.Marks.UUID = t.UUID
-	if err := t.Marks.Validate(); err != nil {
-		return fmt.Errorf("store: opportunity %s: %w", t.UUID, err)
+	opportunity.Marks.UUID = opportunity.UUID
+	if err := opportunity.Marks.Validate(); err != nil {
+		return fmt.Errorf("store: opportunity %s: %w", opportunity.UUID, err)
 	}
 
-	latest := t.LatestReleaseDate
-	for i := range t.Releases {
-		r := &t.Releases[i]
-		if r.ReleaseID == "" {
-			return fmt.Errorf("store: opportunity %s: release %d has no release id", t.UUID, i)
+	latest := opportunity.LatestReleaseDate
+	for i := range opportunity.Releases {
+		release := &opportunity.Releases[i]
+		if release.ReleaseID == "" {
+			return fmt.Errorf("store: opportunity %s: release %d has no release id", opportunity.UUID, i)
 		}
-		r.UUID = t.UUID
-		r.ReleaseDate = r.ReleaseDate.UTC()
-		if r.ReleaseDate.After(latest) {
-			latest = r.ReleaseDate
+		release.UUID = opportunity.UUID
+		release.ReleaseDate = release.ReleaseDate.UTC()
+		if release.ReleaseDate.After(latest) {
+			latest = release.ReleaseDate
 		}
-		for j := range r.Tags {
-			r.Tags[j].UUID = t.UUID
-			r.Tags[j].ReleaseID = r.ReleaseID
+		for tagIndex := range release.Tags {
+			release.Tags[tagIndex].UUID = opportunity.UUID
+			release.Tags[tagIndex].ReleaseID = release.ReleaseID
 		}
 	}
 
 	if latest.IsZero() {
-		return fmt.Errorf("store: opportunity %s has no release date", t.UUID)
+		return fmt.Errorf("store: opportunity %s has no release date", opportunity.UUID)
 	}
 
-	t.LatestReleaseDate = latest.UTC()
-	t.StartDate = utcPtr(t.StartDate)
-	t.EndDate = utcPtr(t.EndDate)
+	opportunity.LatestReleaseDate = latest.UTC()
+	opportunity.StartDate = utcPtr(opportunity.StartDate)
+	opportunity.EndDate = utcPtr(opportunity.EndDate)
 
 	return nil
 }
 
-func utcPtr(t *time.Time) *time.Time {
-	if t == nil {
+func utcPtr(when *time.Time) *time.Time {
+	if when == nil {
 		return nil
 	}
-	u := t.UTC()
-	return &u
+	utc := when.UTC()
+	return &utc
 }
 
 // ftsQuery turns free text into an FTS5 query that requires every word, each
@@ -162,11 +162,11 @@ func utcPtr(t *time.Time) *time.Time {
 // FTS5 syntax (operators, column filters, unbalanced quotes). It returns ""
 // when the text contains no words.
 func ftsQuery(text string) string {
-	words := strings.FieldsFunc(text, func(r rune) bool {
-		return !unicode.IsLetter(r) && !unicode.IsNumber(r)
+	words := strings.FieldsFunc(text, func(char rune) bool {
+		return !unicode.IsLetter(char) && !unicode.IsNumber(char)
 	})
-	for i, w := range words {
-		words[i] = `"` + w + `"*`
+	for i, word := range words {
+		words[i] = `"` + word + `"*`
 	}
 	return strings.Join(words, " ")
 }
@@ -179,9 +179,9 @@ func ftsQuery(text string) string {
 //
 // A database file that doesn't exist is created, and then needs migrating.
 func Open(ctx context.Context, path string, opts ...Option) (*Store, error) {
-	var o options
-	for _, opt := range opts {
-		opt(&o)
+	var settings options
+	for _, option := range opts {
+		option(&settings)
 	}
 
 	sqldb, err := OpenDB(path)
@@ -191,10 +191,12 @@ func Open(ctx context.Context, path string, opts ...Option) (*Store, error) {
 	if err := sqldb.PingContext(ctx); err != nil {
 		return nil, errors.Join(err, sqldb.Close())
 	}
-	if err := prepareSchema(ctx, sqldb, o); err != nil {
+	if err := prepareSchema(ctx, sqldb, settings); err != nil {
 		return nil, errors.Join(err, sqldb.Close())
 	}
-	return &Store{db: sqlx.NewDb(sqldb, "sqlite3")}, nil
+	return &Store{
+		db: sqlx.NewDb(sqldb, "sqlite3"),
+	}, nil
 }
 
 // Close closes the database.
@@ -214,20 +216,24 @@ type opportunityRow struct {
 	types.Opportunity
 }
 
-// SaveOpportunity stores t and its releases in one transaction.
+// SaveOpportunity stores opportunity and its releases in one transaction.
 //
 // Releases (and their tags) are write-once: ones already stored are skipped.
-// The opportunity row and its classifications are replaced only if t's newest
-// release is at least as new as the release the stored opportunity came from, so
-// a late-arriving older release never undoes a newer one.
+// The opportunity row and its classifications are replaced only if the
+// opportunity's newest release is at least as new as the release the stored
+// opportunity came from, so a late-arriving older release never undoes a
+// newer one.
 //
-// t.Marks are stored only for a new opportunity; existing marks are kept (use
-// SetMarks to change them).
+// opportunity.Marks are stored only for a new opportunity; existing marks are
+// kept (use SetMarks to change them).
 //
-// t is normalised in place (see prepareOpportunity), and when the opportunity is
+// opportunity is normalised in place (see prepareOpportunity), and when it is
 // written its classifications' IDs are filled in.
-func (s *Store) SaveOpportunity(ctx context.Context, t *types.Opportunity) (SaveResult, error) {
-	if err := prepareOpportunity(t); err != nil {
+func (s *Store) SaveOpportunity(
+	ctx context.Context,
+	opportunity *types.Opportunity,
+) (SaveResult, error) {
+	if err := prepareOpportunity(opportunity); err != nil {
 		return SaveResult{}, err
 	}
 
@@ -237,7 +243,7 @@ func (s *Store) SaveOpportunity(ctx context.Context, t *types.Opportunity) (Save
 	}
 	defer tx.Rollback() //nolint:errcheck // no-op after Commit
 
-	res, _, err := saveOpportunity(ctx, tx, t)
+	res, _, err := saveOpportunity(ctx, tx, opportunity)
 	if err != nil {
 		return SaveResult{}, err
 	}
@@ -247,23 +253,25 @@ func (s *Store) SaveOpportunity(ctx context.Context, t *types.Opportunity) (Save
 	return res, nil
 }
 
-// SaveOpportunities stores t and its releases in one transaction.
+// SaveOpportunities stores each of opportunities and its releases, all in one
+// transaction, as SaveOpportunity does for one.
 //
 // Releases (and their tags) are write-once: ones already stored are skipped.
-// The opportunity row and its classifications are replaced only if t's newest
-// release is at least as new as the release the stored opportunity came from, so
-// a late-arriving older release never undoes a newer one.
+// An opportunity row and its classifications are replaced only if the
+// opportunity's newest release is at least as new as the release the stored
+// opportunity came from, so a late-arriving older release never undoes a
+// newer one.
 //
-// t.Marks are stored only for a new opportunity; existing marks are kept (use
+// Marks are stored only for a new opportunity; existing marks are kept (use
 // SetMarks to change them).
 //
-// t is normalised in place (see prepareOpportunity), and when the opportunity is
-// written its classifications' IDs are filled in.
+// Each opportunity is normalised in place (see prepareOpportunity), and when
+// it is written its classifications' IDs are filled in.
 func (s *Store) SaveOpportunities(
 	ctx context.Context, opportunities []*types.Opportunity,
 ) (SaveMultipleResult, error) {
-	for _, t := range opportunities {
-		if err := prepareOpportunity(t); err != nil {
+	for _, opportunity := range opportunities {
+		if err := prepareOpportunity(opportunity); err != nil {
 			return SaveMultipleResult{}, err
 		}
 	}
@@ -274,9 +282,11 @@ func (s *Store) SaveOpportunities(
 	}
 	defer tx.Rollback() //nolint:errcheck // no-op after Commit
 
-	allRes := SaveMultipleResult{OpportunityResults: make([]SaveResult, len(opportunities))}
-	for i, t := range opportunities {
-		res, isNew, err := saveOpportunity(ctx, tx, t)
+	allRes := SaveMultipleResult{
+		OpportunityResults: make([]SaveResult, len(opportunities)),
+	}
+	for i, opportunity := range opportunities {
+		res, isNew, err := saveOpportunity(ctx, tx, opportunity)
 		if err != nil {
 			return SaveMultipleResult{}, err
 		}
@@ -300,27 +310,35 @@ func (s *Store) SaveOpportunities(
 // one prepared opportunity inside tx. isNew reports that the opportunity was
 // not already stored.
 func saveOpportunity(
-	ctx context.Context, tx *sqlx.Tx, t *types.Opportunity,
+	ctx context.Context, tx *sqlx.Tx, opportunity *types.Opportunity,
 ) (res SaveResult, isNew bool, err error) {
 	var stored time.Time
-	err = tx.GetContext(ctx, &stored, selectOpportunityLatestReleaseDate, t.UUID)
+	err = tx.GetContext(ctx, &stored, selectOpportunityLatestReleaseDate, opportunity.UUID)
 	switch {
 	case errors.Is(err, sql.ErrNoRows):
 		isNew = true
 		res.OpportunityUpdated = true
 	case err != nil:
-		return SaveResult{}, false, fmt.Errorf("store: reading opportunity %s: %w", t.UUID, err)
+		return SaveResult{}, false, fmt.Errorf(
+			"store: reading opportunity %s: %w",
+			opportunity.UUID,
+			err,
+		)
 	default:
-		res.OpportunityUpdated = !t.LatestReleaseDate.Before(stored)
+		res.OpportunityUpdated = !opportunity.LatestReleaseDate.Before(stored)
 	}
 	if res.OpportunityUpdated {
-		if err := writeOpportunity(ctx, tx, t); err != nil {
-			return SaveResult{}, false, fmt.Errorf("store: writing opportunity %s: %w", t.UUID, err)
+		if err := writeOpportunity(ctx, tx, opportunity); err != nil {
+			return SaveResult{}, false, fmt.Errorf(
+				"store: writing opportunity %s: %w",
+				opportunity.UUID,
+				err,
+			)
 		}
 	}
 
-	for _, r := range t.Releases {
-		inserted, err := insertReleaseWithTags(ctx, tx, r)
+	for _, release := range opportunity.Releases {
+		inserted, err := insertReleaseWithTags(ctx, tx, release)
 		if err != nil {
 			return SaveResult{}, false, err
 		}
@@ -331,69 +349,86 @@ func saveOpportunity(
 	return res, isNew, nil
 }
 
-// insertReleaseWithTags stores r and its tags unless r is already stored, and
-// reports whether it was inserted.
+// insertReleaseWithTags stores release and its tags unless it is already
+// stored, and reports whether it was inserted.
 func insertReleaseWithTags(
-	ctx context.Context, tx *sqlx.Tx, r types.OpportunityRelease,
+	ctx context.Context, tx *sqlx.Tx, release types.OpportunityRelease,
 ) (bool, error) {
-	result, err := tx.NamedExecContext(ctx, insertRelease, r)
+	result, err := tx.NamedExecContext(ctx, insertRelease, release)
 	if err != nil {
-		return false, fmt.Errorf("store: inserting release %s/%s: %w", r.UUID, r.ReleaseID, err)
+		return false, fmt.Errorf(
+			"store: inserting release %s/%s: %w",
+			release.UUID,
+			release.ReleaseID,
+			err,
+		)
 	}
-	if n, err := result.RowsAffected(); err != nil || n == 0 {
+	if affected, err := result.RowsAffected(); err != nil || affected == 0 {
 		return false, err // n == 0: already stored
 	}
-	for _, tag := range r.Tags {
+	for _, tag := range release.Tags {
 		if _, err := tx.NamedExecContext(ctx, insertReleaseTag, tag); err != nil {
 			return false, fmt.Errorf(
-				"store: inserting tag for %s/%s: %w", r.UUID, r.ReleaseID, err,
+				"store: inserting tag for %s/%s: %w", release.UUID, release.ReleaseID, err,
 			)
 		}
 	}
 	return true, nil
 }
 
-// writeOpportunity upserts t's row, gives it a marks row if it has none
+// writeOpportunity upserts opportunity's row, gives it a marks row if it has none
 // (existing marks are kept), and replaces its classifications, filling in
 // their IDs.
-func writeOpportunity(ctx context.Context, tx *sqlx.Tx, t *types.Opportunity) (err error) {
-	if _, err := tx.NamedExecContext(ctx, upsertOpportunity, t); err != nil {
+func writeOpportunity(
+	ctx context.Context,
+	tx *sqlx.Tx,
+	opportunity *types.Opportunity,
+) (err error) {
+	if _, err := tx.NamedExecContext(ctx, upsertOpportunity, opportunity); err != nil {
 		return err
 	}
-	if _, err := tx.NamedExecContext(ctx, insertOpportunityMarks, t.Marks); err != nil {
+	if _, err := tx.NamedExecContext(ctx, insertOpportunityMarks, opportunity.Marks); err != nil {
 		return err
 	}
-	if _, err := tx.ExecContext(ctx, deleteOpportunityClassifications, t.UUID); err != nil {
+	if _, err := tx.ExecContext(ctx, deleteOpportunityClassifications, opportunity.UUID); err != nil {
 		return err
 	}
 
-	stmt, err := tx.PrepareNamedContext(ctx, upsertClassificationCodeReturningID)
+	statement, err := tx.PrepareNamedContext(ctx, upsertClassificationCodeReturningID)
 	if err != nil {
 		return err
 	}
-	defer func() { err = errors.Join(err, stmt.Close()) }()
-	for i := range t.Classifications {
-		c := &t.Classifications[i]
-		if err := stmt.GetContext(ctx, &c.ID, c); err != nil {
+	defer func() {
+		err = errors.Join(err, statement.Close())
+	}()
+	for i := range opportunity.Classifications {
+		classification := &opportunity.Classifications[i]
+		if err := statement.GetContext(ctx, &classification.ID, classification); err != nil {
 			return err
 		}
-		if _, err := tx.ExecContext(ctx, insertOpportunityClassification, t.UUID, c.ID); err != nil {
+		if _, err := tx.ExecContext(
+			ctx,
+			insertOpportunityClassification,
+			opportunity.UUID,
+			classification.ID,
+		); err != nil {
 			return err
 		}
 	}
 	return nil
 }
 
-// SetMarks replaces the marks of the opportunity m.UUID, or returns ErrNotFound.
-// Marks that fail m.Validate (e.g. types.ErrWonAndLost) are not stored.
-func (s *Store) SetMarks(ctx context.Context, m types.OpportunityMarks) error {
-	if m.UUID == "" {
+// SetMarks replaces the marks of the opportunity marks.UUID, or returns
+// ErrNotFound. Marks that fail marks.Validate (e.g. types.ErrWonAndLost) are
+// not stored.
+func (s *Store) SetMarks(ctx context.Context, marks types.OpportunityMarks) error {
+	if marks.UUID == "" {
 		return errors.New("store: marks have no UUID")
 	}
-	if err := m.Validate(); err != nil {
-		return fmt.Errorf("store: opportunity %s: %w", m.UUID, err)
+	if err := marks.Validate(); err != nil {
+		return fmt.Errorf("store: opportunity %s: %w", marks.UUID, err)
 	}
-	_, err := s.db.NamedExecContext(ctx, upsertOpportunityMarks, m)
+	_, err := s.db.NamedExecContext(ctx, upsertOpportunityMarks, marks)
 	if isForeignKeyError(err) {
 		return ErrNotFound
 	}
@@ -403,8 +438,8 @@ func (s *Store) SetMarks(ctx context.Context, m types.OpportunityMarks) error {
 // isForeignKeyError reports whether err is SQLite rejecting a write that
 // breaks a foreign key, e.g. one referring to a missing opportunity.
 func isForeignKeyError(err error) bool {
-	var se sqlite3.Error
-	return errors.As(err, &se) && se.ExtendedCode == sqlite3.ErrConstraintForeignKey
+	var sqliteErr sqlite3.Error
+	return errors.As(err, &sqliteErr) && sqliteErr.ExtendedCode == sqlite3.ErrConstraintForeignKey
 }
 
 // GetOpportunity returns the opportunity with its classifications, marks and
@@ -431,13 +466,14 @@ func (s *Store) GetOpportunity(ctx context.Context, uuid string) (*types.Opportu
 	return &opportunities[0], nil
 }
 
-// ListOpportunities returns opportunities matching f, with their classifications
-// and marks but without releases (use ListReleases or GetOpportunity for those).
+// ListOpportunities returns opportunities matching filter, with their
+// classifications and marks but without releases (use ListReleases or
+// GetOpportunity for those).
 func (s *Store) ListOpportunities(
 	ctx context.Context,
-	f OpportunityFilter,
+	filter OpportunityFilter,
 ) ([]types.Opportunity, error) {
-	query, args := listOpportunitiesQuery(f)
+	query, args := listOpportunitiesQuery(filter)
 	var rows []opportunityRow
 	if err := s.db.SelectContext(ctx, &rows, query, args...); err != nil {
 		return nil, err
@@ -457,44 +493,62 @@ func (s *Store) ListOpportunities(
 
 // listOpportunitiesQuery assembles the ListOpportunities query from the fragments in
 // queries.go, with one argument per filter that is set (none for mark filters).
-func listOpportunitiesQuery(f OpportunityFilter) (string, []any) {
+func listOpportunitiesQuery(filter OpportunityFilter) (string, []any) {
 	var where []string
 	var args []any
-	add := func(clause string, arg any) {
+	add := func(clause string, argument any) {
 		where = append(where, clause)
-		args = append(args, arg)
+		args = append(args, argument)
 	}
-	if f.Status != "" {
-		add(filterOpportunityStatus, f.Status)
+	if filter.Status != "" {
+		add(filterOpportunityStatus, filter.Status)
 	}
-	if f.ClassificationCode != "" {
-		add(filterOpportunityClassificationCode, f.ClassificationCode)
+	if filter.ClassificationCode != "" {
+		add(filterOpportunityClassificationCode, filter.ClassificationCode)
 	}
-	if q := ftsQuery(f.Title); q != "" {
-		add(filterOpportunityTitleMatch, q)
+	if match := ftsQuery(filter.Title); match != "" {
+		add(filterOpportunityTitleMatch, match)
 	}
-	if !f.ReleasedFrom.IsZero() {
-		add(filterOpportunityReleasedFrom, f.ReleasedFrom.UTC())
+	if !filter.ReleasedFrom.IsZero() {
+		add(filterOpportunityReleasedFrom, filter.ReleasedFrom.UTC())
 	}
-	if !f.ReleasedBefore.IsZero() {
-		add(filterOpportunityReleasedBefore, f.ReleasedBefore.UTC())
+	if !filter.ReleasedBefore.IsZero() {
+		add(filterOpportunityReleasedBefore, filter.ReleasedBefore.UTC())
 	}
-	for _, m := range []struct {
+	for _, mark := range []struct {
 		filter MarkFilter
 		clause string
 	}{
-		{f.Hidden, filterOpportunityMarkHidden},
-		{f.Skipped, filterOpportunityMarkSkipped},
-		{f.Interested, filterOpportunityMarkInterested},
-		{f.BidSubmitted, filterOpportunityMarkBidSubmitted},
-		{f.Won, filterOpportunityMarkWon},
-		{f.Lost, filterOpportunityMarkLost},
+		{
+			filter: filter.Hidden,
+			clause: filterOpportunityMarkHidden,
+		},
+		{
+			filter: filter.Skipped,
+			clause: filterOpportunityMarkSkipped,
+		},
+		{
+			filter: filter.Interested,
+			clause: filterOpportunityMarkInterested,
+		},
+		{
+			filter: filter.BidSubmitted,
+			clause: filterOpportunityMarkBidSubmitted,
+		},
+		{
+			filter: filter.Won,
+			clause: filterOpportunityMarkWon,
+		},
+		{
+			filter: filter.Lost,
+			clause: filterOpportunityMarkLost,
+		},
 	} {
-		switch m.filter {
+		switch mark.filter {
 		case MarkSet:
-			where = append(where, m.clause)
+			where = append(where, mark.clause)
 		case MarkUnset:
-			where = append(where, "NOT "+m.clause)
+			where = append(where, "NOT "+mark.clause)
 		}
 	}
 
@@ -503,7 +557,7 @@ func listOpportunitiesQuery(f OpportunityFilter) (string, []any) {
 		query += "\nWHERE " + strings.Join(where, "\n\tAND ")
 	}
 	query += listOpportunitiesOrderAndPage
-	return query, append(args, f.limit(), f.Offset)
+	return query, append(args, filter.limit(), filter.Offset)
 }
 
 // loadClassifications fills in Classifications for all opportunities with one query.
@@ -530,9 +584,9 @@ func (s *Store) loadClassifications(ctx context.Context, opportunities []types.O
 	if err := s.db.SelectContext(ctx, &rows, s.db.Rebind(query), args...); err != nil {
 		return err
 	}
-	for _, r := range rows {
-		t := byUUID[r.OpportunityUUID]
-		t.Classifications = append(t.Classifications, r.ClassificationCode)
+	for _, releaseRow := range rows {
+		opportunity := byUUID[releaseRow.OpportunityUUID]
+		opportunity.Classifications = append(opportunity.Classifications, releaseRow.ClassificationCode)
 	}
 	return nil
 }
@@ -548,7 +602,9 @@ func (s *Store) loadMarks(ctx context.Context, opportunities []types.Opportunity
 	for i := range opportunities {
 		uuids[i] = opportunities[i].UUID
 		byUUID[opportunities[i].UUID] = &opportunities[i]
-		opportunities[i].Marks = types.OpportunityMarks{UUID: opportunities[i].UUID}
+		opportunities[i].Marks = types.OpportunityMarks{
+			UUID: opportunities[i].UUID,
+		}
 	}
 
 	query, args, err := sqlx.In(selectMarksForOpportunities, uuids)
@@ -559,8 +615,8 @@ func (s *Store) loadMarks(ctx context.Context, opportunities []types.Opportunity
 	if err := s.db.SelectContext(ctx, &rows, s.db.Rebind(query), args...); err != nil {
 		return err
 	}
-	for _, m := range rows {
-		byUUID[m.UUID].Marks = m
+	for _, row := range rows {
+		byUUID[row.UUID].Marks = row
 	}
 	return nil
 }
@@ -581,8 +637,8 @@ func (s *Store) ListReleases(ctx context.Context, uuid string) ([]types.Opportun
 		return nil, err
 	}
 	for _, tag := range tags {
-		if r := byID[tag.ReleaseID]; r != nil {
-			r.Tags = append(r.Tags, tag)
+		if release := byID[tag.ReleaseID]; release != nil {
+			release.Tags = append(release.Tags, tag)
 		}
 	}
 	return releases, nil