classifying code comments in java OSS systems

luca pascarella, alberto bacchelli

taxonomy of code comments

they say that commented code is better code, but that’s contrary to what i’ve found when practicioners talk about beautiful code

categories of code comments:

1. purpose (functionality)
   1. summary (behaviour, what)
   2. expand (more details)
   3. rationale (why)
2. notice (these are the bad ones)
   1. usage
   2. deprecation
   3. exception
3. under development (bad ones as well)
   1. todo
   2. incomplete
   3. commented out code
4. style and IDE (also bad)
   1. directive
   2. formatter
5. metadata
   1. license
   2. ownership
   3. pointer (link/url)
6. discarded
   1. noise
   2. automatic generation of stubs