Code comment narration and over-explanation
Parent: LLM tells in code, commit messages, comments and READMEs · Published reference · snapshot 2026-09-23
↓ Facts as markdownall context files
Source-anchored research for Code comment narration and over-explanation. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
Definitions
- The characteristic narration tell is a comment that restates the adjacent code, adding maintenance burden and burying the few comments that matter. (low confidence) [source]
- Comment-based detection is a weak, proxy signal: the repository study calls its results proxy-based and warns detectors both under- and over-estimate LLM use, and other work reports commercial detectors are affected by comments and unreliable. (medium confidence) [source]
Structure and components
- Agent guidance for avoiding the tell: do not add comments by default; add one only for non-obvious why (rationale, constraints, invariants, trade-offs, surprising external behavior); prefer better names, types and structure over narration. (low confidence) (verified as of 2026-09-04) [source]
Measurements and reference values
- LLM comments are not uniformly poor: in a 415-comment Java evaluation, human experts judged 58.8% to match originals and 27.7% to surpass them; automated metrics such as BLEU correlated negatively with human judgment. (low confidence) [source]
Facts and statements
- A 2021-2025 study of eight GitHub repositories found comments flagged as likely LLM-generated concentrated in Meta and Explanation categories, and remained relatively stable over time. (medium confidence) (verified as of 2026-07-01) [source]
Children
- No children recorded.