Lines of comments in files¶
ID: cs/lines-of-comments-in-files
Kind: treemap
Severity:
Precision:
Tags:
- maintainability
- documentation
Click to see the query in the CodeQL repository
This metric measures the (absolute) number of comment lines per file. Whilst this is not especially meaningful out of context a low number of comments may indicate files that are difficult to understand due to poor documentation.
Recommendation¶
Consider if the file needs more documentation. Short files might not but most files should have at least a comment explaining their purpose.
References¶
Jeff Atwood. Avoiding Undocumentation. 2005.
Steve McConnell. Code Complete. 2nd Edition. Microsoft Press. 2004.