12250 shaares
293 private links
293 private links
During my research I identified nine types of comments:
- Function comments: They prevent the reader from reading code in the first place. Instead, after reading the comment, it should be possible to consider some code as a black box that should obey certain rules
- Design comments: they states how and why a given piece of code uses certain algorithms, techniques, tricks, and implementation. [...] With such background, reading the code will be simpler.
- Why comments: explain the reason why the code is doing something, even if what the code is doing is crystal clear.
- Teacher comments: They teach instead the domain (for example math, computer graphics, networking, statistics, complex data structures) in which the code is operating, that may be one outside of the reader skills set, or is simply too full of details to recall all them from memory.
- Checklist comments: sometimes because of language limitations, design issues, or simply because of the natural complexity arising in systems, it is not possible to centralize a given concept or interface in one piece, so there are places in the code that tells you to remember to do things in some other place of the code
- Guide comments: they do a single thing: they babysit the reader, assist him or her while processing what is written in the source code by providing clear division, rhythm, and introducing what you are going to read.
- Trivial comments: a bad one, a guide comment where the cognitive load of reading the comment is the same or higher than just reading the associated code.
- Debt comments: debt comments are technical debts statements hard coded inside the source code itself:
- Backup comments: the developer comments older versions of some code block or even a whole function, because she or he is insecure about the change that was operated in the new one. We have git now.
Comments can be considered analysis tools; and they are often harder to write than code.