How To Think Like A Programmer [video]
“Comments aren’t there to explain code to other programmers. Code is there to explain the comments to the computer”
I think everyone who wants to be a better programmer needs to watch this video
thanks for the video, I think this is the most important part that differentiates an
Experienced / Monster programmers from the Normal programmers
My personal philosophy is “code should read like a comment”. Name your functions and variables something sensible and most of the time you won’t even need a comment. Comments are there to explain code that does something that would be otherwise unintuitive or inscrutable, not to repeat the code again in comment form (and possibly get out of sync). Comments are not a tutorial on the source language, nor are they a substitute for documentation (save for those that are specifically generated into documentation).
The first thing I do with code that is half comments or more is delete the noise and start renaming and refactoring things until the code makes sense on its own. Then if it’s a publicly available API method, it gets documentation comments, otherwise not. Comments are for programmers (including yourself). Documentation is for the users.
Understand that I’m not railing against comments in general, just the idea that they can substitute for clearly written code. If none of the code can be understood without comments, then there’s something seriously wrong with the code that no amount of comments can fix.