about comments why the code is doing a certain action, or why it’s doing something that is clear instead of something else that would feel more natural.
So comments can be, for me, a tool for lowering the cognitive load of the reader.
-
Function comments : prevent the reader from reading code in the first place, a form of in-line API documentation
-
Design comments : While a "function comment" is usually located at the start of a function, a design comment is more often located at the start of a file
-
Why comments : 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)
-
Checklist comments
-
Guide comments : sole reason to exist is to lower the cognitive load of the programmer reading some code.
-
Trivial comments : is a guide comment where the cognitive load of reading the comment is the same or higher than just reading the associated code
-
Debt comments : I was kind of afraid that later I would no longer remember what were the entry points to do the garbage collection, so I put TODO comments, and even wrote the trigger condition.
-
Backup comments