- 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
RAW Paste Data