In an attempt to dispel the “I don’t need to comment my code since if the code is written clearly enough it should describe itself” theory, I present the following:
The purpose of code comments is to present intent.
A software defect is a deviation from intent. This definition does not make a distinction between implicit (i.e. expected but not defined in a requirement) and explicit (i.e. defined in a requirement) intent.
Code is incapable of sufficiently presenting desired intent.
Proof I will provide an indirect proof of Theorem 1.1 by assuming “code is capable of sufficiently presenting desired intent” and obtaining a contradition. Choose a section of code that contains defects. By Definition 1.2 this section of code does not correctly describe the intent. QED
Notice that Theorem 1.1 contains the word desired. This is necessary to distinguish between the intent that a section of code with defects presents and the intent that is required. Also notice that Theorem 1.1 contains the word sufficiently. Later entries will expound on this in more depth but for now it will suffice to say that code utilizing crafty programming may obfuscate intent.
I do acknowledge that for those who use the “I don’t need to comment my code since if the code is written clearly enough it should describe itself” to mean “I’m too cool / talented / whatever to comment” or to cover for “I’m too lazy to comment” that my argument will have fallen on deaf ears. I’m getting to you next!