7.2.6. Dokumentation und Tests

Dokumentation in Go ist die API auf pkg.go.dev. Tests sind oft Tabellen – und Example…-Funktionen sind beides: Doku und ausführbarer Check.

Kommentare direkt vor Top-Level-Deklarationen (ohne Leerzeile) werden zu Package-Dokumentation. Alle exportierten Namen brauchen einen Doc Comment; nicht-triviale unexportierte oft auch.

// Request represents a request to run a command.
type Request struct { /* ... */ }

// Encode writes the JSON encoding of req to w.
func Encode(w io.Writer, req *Request) error { /* ... */ }

Vollständige Sätze, beginnend mit dem Namen des Symbols, endend mit Punkt:

// Package math provides basic constants and mathematical functions.
package math

Package-Kommentare sitzen unmittelbar vor der package-Zeile. Bevorzugt //; /* */ vor allem für Package-Blöcke.

Wie die API zu verwenden ist – nicht jede Implementierungszeile nacherzählen. Invarianten, Einheiten, Nil-Verhalten und wichtige Sentinel-/Fehler-Typen dokumentieren. Offensichtliches weglassen.

Example… in _test.go erscheint in godoc und läuft als Test, wenn ein Output:- (oder Unordered output:-) Kommentar gesetzt ist. Beim Anlegen eines Packages die vorgesehene Nutzung mitbelegen.

Viele Fälle als Tabelle (Slice oder Map von Structs), eine Schleife prüft. Kopierte Testfunktionen sind oft ein Hinweis auf eine Tabelle. Mit t.Run bleiben Fehlschläge benannt.

func TestSprintfFlags(t *testing.T) {
	tests := []struct {
		in  string
		out string
	}{
		{"%a", "[%a]"},
		{"%-a", "[%-a]"},
	}
	for _, tt := range tests {
		t.Run(tt.in, func(t *testing.T) {
			s := Sprintf(tt.in, &flagprinter)
			if s != tt.out {
				t.Errorf("got %q, want %q", s, tt.out)
			}
		})
	}
}

if got != tt.want {
	t.Errorf("Foo(%q) = %d; want %d", tt.in, got, tt.want)
}

Eingaben, Ist und Soll zeigen – ohne Assert-Helper, die Details verstecken.

t.Errorf protokolliert und macht weiter (mehrere Fälle sichtbar). t.Fatalf / FailNow bricht die aktuelle Testfunktion ab. Setup-Fehler: t.Fatal(err), nicht panic.

import . "foo" nur in seltenen Zyklusfällen.

t.Context() / b.Context() liefern einen Context, der nach dem Test und vor Cleanup abgebrochen wird – besser als ein selbst gebautes Cancel nur für die Testdauer.

Diese Seite gehört zu 7.2. Clean Code.