CodeQL documentation

Lines of comments in files

ID: java/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 number of comment lines for each file.

Whilst the absolute number of comment lines in a file may not provide much useful information out of context, a very small number of comments in a file may indicate either a potentially worrying lack of documentation or that the file was generated by an automated tool - a quick visual inspection should be sufficient to distinguish between the two cases.

Recommendation

If the file is not an auto-generated one, it should be documented at the first convenient opportunity (i.e. now). We note in passing that:

  • From a pragmatic standpoint, it is clear that not all files are equally important to document, so some common sense needs to be applied when deciding which code should be documented first.

  • Documenting entire files after the fact is not only onerous, but also often yields lower-quality documentation than would have been written by the original author at the time of writing the code (because other developers may not understand the context as well as the person who wrote the code). For this reason, finding completely undocumented files should be treated as a sign that your documentation practices in general need to improve.

References

  • S. McConnell. Code Complete, 2nd Edition. Microsoft Press, 2004.

  • © GitHub, Inc.
  • Terms
  • Privacy