comment-ratio

Overview ¶

Measure how much of a change is comment rather than code.

Usage:

go run ./scripts/comment-ratio -base origin/main
go run ./scripts/comment-ratio -base <sha> -head <sha> -per-file
go run ./scripts/comment-ratio -base origin/main -max-inline-ratio 0.25

Unlike a per-comment classifier, this makes no judgement about any individual comment, so rewording cannot move the number: only writing fewer comment lines can. That makes it a volume signal rather than a quality one.

Added lines are classified against the full parsed file, so doc comments are attributed through go/ast Doc fields rather than guessed from the diff hunk. Lines are reported in three classes:

doc     comment lines attached to a declaration as its godoc
inline  every other comment line
code    non-blank, non-comment

inline_ratio (inline/code) is the actionable signal. Doc comments are counted separately because documenting an exported symbol is required by convention and should not read as noise.