Doc Comment Starts With Name
ID |
go.doc_comment_starts_with_name |
Severity |
low |
Remediation Complexity |
trivial |
Remediation Risk |
low |
Remediation Effort |
low |
Resource |
Documentation |
Language |
Go |
Tags |
CWE:1116, code-style, documentation |
Description
Reports an exported declaration whose doc comment does not begin with the declared identifier’s name.
Rationale
Go convention, followed by go doc and the standard library, renders the doc comment of an exported
function, type, variable or constant as a sentence about that name, so the comment is expected to
start with the name (// Process reads … above func Process()). A comment that starts otherwise
reads awkwardly in generated documentation and breaks the convention readers rely on. The check fires
only when a doc comment is actually present on an exported declaration; a declaration with no doc
comment is left to the missing-documentation rule, and unexported declarations are not checked.
// This reads the file.
func Process() {} // FLAW — comment should start with "Process"
// Process reads the file.
func Process() {} // OK