docs: add constructor-first rule to test ordering conventions

mwbrooks · mwbrooks · commit 3629e3f93382 · 2026-03-16T16:25:05.000-07:00
Update CLAUDE.md and MAINTAINERS_GUIDE.md to state that constructor
functions (NewXYZ) should always be declared first at the top of test
files, before alphabetically ordered test functions. Also allow
exceptions when alphabetical ordering doesn't work well. Apply the
new rule to iostreams_test.go by moving Test_IOSteams_NewIOStreams
to the top of the file.
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
@@ -146,7 +146,7 @@ func Test_getKeyLength(t *testing.T) { ... }         // package-level function
 
 ### Test Ordering Conventions
 
-Test functions should be ordered alphabetically within each file. When a file has logical sections (separated by comments), tests should be alphabetical within each section. Getter and setter functions are grouped together under the base name — ignore the `Get` or `Set` prefix when determining order (e.g. `Test_AppName` and `Test_SetAppName` both sort under `A`).
+Constructor functions (`NewXYZ`) should always be declared first, at the top of the test file. After constructors, test functions should be ordered alphabetically within each file. When a file has logical sections (separated by comments), tests should be alphabetical within each section. Getter and setter functions are grouped together under the base name — ignore the `Get` or `Set` prefix when determining order (e.g. `Test_AppName` and `Test_SetAppName` both sort under `A`). Exceptions to alphabetical ordering can be made when it doesn't work well for readability or logical grouping.
 
 ### Table-Driven Test Conventions
 
diff --git a/.github/MAINTAINERS_GUIDE.md b/.github/MAINTAINERS_GUIDE.md
@@ -399,14 +399,18 @@ func Test_getKeyLength(t *testing.T) { ... }
 
 #### Test ordering conventions
 
-Test functions should be ordered alphabetically within each file. When a file has
-logical sections (separated by comments), tests should be alphabetical within each
-section.
+Constructor functions (`NewXYZ`) should always be declared first, at the top of the
+test file. After constructors, test functions should be ordered alphabetically. When
+a file has logical sections (separated by comments), tests should be alphabetical
+within each section.
 
 Getter and setter functions should be grouped together under the base name. Ignore
 the `Get` or `Set` prefix when determining alphabetical order. For example,
 `Test_AppName` and `Test_SetAppName` are both sorted under `A` for `AppName`.
 
+Exceptions to alphabetical ordering can be made when it doesn't work well for
+readability or logical grouping.
+
 #### Contributing tests
 
 If you'd like to add tests, please review our
diff --git a/internal/iostreams/iostreams_test.go b/internal/iostreams/iostreams_test.go
@@ -25,6 +25,16 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+func Test_IOSteams_NewIOStreams(t *testing.T) {
+	var io *IOStreams
+	fsMock := slackdeps.NewFsMock()
+	osMock := slackdeps.NewOsMock()
+	config := config.NewConfig(fsMock, osMock)
+	config.DebugEnabled = true
+	io = NewIOStreams(config, fsMock, osMock)
+	require.True(t, io.config.DebugEnabled, "iostreams references config")
+}
+
 func Test_IOStreams_ExitCode(t *testing.T) {
 	tests := map[string]struct {
 		setCode  ExitCode
@@ -55,16 +65,6 @@ func Test_IOStreams_ExitCode(t *testing.T) {
 	}
 }
 
-func Test_IOSteams_NewIOStreams(t *testing.T) {
-	var io *IOStreams
-	fsMock := slackdeps.NewFsMock()
-	osMock := slackdeps.NewOsMock()
-	config := config.NewConfig(fsMock, osMock)
-	config.DebugEnabled = true
-	io = NewIOStreams(config, fsMock, osMock)
-	require.True(t, io.config.DebugEnabled, "iostreams references config")
-}
-
 func Test_IOStreams_IsTTY(t *testing.T) {
 	tests := map[string]struct {
 		fileInfo os.FileInfo
