The only time I leave a comment is with a TODO tag where I plan to comeback and remedy the problem later and remove said comment. I think contract comments are generally fine as long they are kept up to date.. anything else should be auto generated..
The problem with code as documentation is that the code tells you what the program does, it doesn't tell you what the programmer wanted to happen. The ridiculously simple example I use is to imagine seeing the following in a piece of code: // Increment the counter counter = counter - 1; Now without comments a future developer trying to proof read or fix an error in this code has to scan back and forwards through the entire chunk of code to try and figure out what is the error while the commented version will immediately jump out as a mismatch to a reader.
@ThePassionateProgrammer carefully crafting function and variable name goes a long way to self documentation of code. I used to program in FORTH, and took great delight in the art of self commenting code, though you still had plings and bangs at the lowest level to deal with.
I think your camera is out of focus, please check your settings. Audio is perfect.
Sorry about that. I’ll use a better camera next time.
The only time I leave a comment is with a TODO tag where I plan to comeback and remedy the problem later and remove said comment. I think contract comments are generally fine as long they are kept up to date.. anything else should be auto generated..
Yeah, I forgot to mention that TODO tags in comments are fine. Thank you for pointing it out.
The problem with code as documentation is that the code tells you what the program does, it doesn't tell you what the programmer wanted to happen. The ridiculously simple example I use is to imagine seeing the following in a piece of code:
// Increment the counter
counter = counter - 1;
Now without comments a future developer trying to proof read or fix an error in this code has to scan back and forwards through the entire chunk of code to try and figure out what is the error while the commented version will immediately jump out as a mismatch to a reader.
Yeah, but at least you know which one the computer believes is correct.
To me a comment is either a lie or an apology.
I thank that is so profound. Thank you for sharing that, Steve!
Great way to say it.
I never put comments in my code. Wait, do I write code?
Do you write code?
You want "why" not "what".
Yes, we actually want both why and what.
@ThePassionateProgrammer carefully crafting function and variable name goes a long way to self documentation of code. I used to program in FORTH, and took great delight in the art of self commenting code, though you still had plings and bangs at the lowest level to deal with.