Missing Package Comment
ID |
go.missing_package_comment |
Severity |
info |
Remediation Complexity |
trivial |
Remediation Risk |
low |
Remediation Effort |
low |
Resource |
Documentation |
Language |
Go |
Tags |
best-practice, documentation |
Description
Reports a Go source file whose package clause has no package doc comment on the line directly
above it.
Rationale
Go convention treats the comment block immediately preceding the package clause — with no
intervening blank line — as the package’s documentation, surfaced by go doc and pkg.go.dev.
A package with no such comment is undocumented: readers and tooling get no one-line summary of
what it is for. A copyright or license header separated from the clause by a blank line does not
count, because the toolchain does not treat it as package documentation.
// Package widget renders widgets.
package widget // OK — documented
package main // FLAW — no package doc commentRemediation
Add a comment immediately above the package clause, conventionally starting with
Package <name> …, describing the package’s purpose.