If you're commenting about the code, do.
There's a huge difference in the value between one or the other.
Therefore, comments should only be used for things like psuedocode, or as help for fellow developers during dev.
Then, they should be removed once the code is done.
But yea, not a good idea.
If you can make your code more clear, so that comments aren't necessary to explain what it does or how it works, that is probably (but not always!) something you should do. But that doesn't mean you shouldn't have comments. At the very least there should be comments explaining why (or why not) things were done a certain way.
It happens occasionally, but it's usually a sign that I'm doing something wrong.
IMHO that rule can be generalized: Whenever you make rules for other devs, make sure that the assumptions on which those rules are based are true, lest you interfere with their work in a negative way.
RunFewerTimesSlowerAndSimplerAlgorithmAfterConsideringTradeOffs()
But one shouls be careful not to mentally think of this as a zero sum dichtomy, where you either have well named functions XOR you have comments, because in reality choosingn both is often the golden path to success.
The danger is of course that code that is totally obvious to you now will take far more time to become as obvious later, be it to your future self or to your psychopathic lunatic co-worker who knows where you live.
So very often code can be made more readable by adding comments, even if it is just saying the same thing with other words, just by reducing ambiguity. Comments can also bridge higher level concepts in a good way, e.g. by you explaining in a few lines how a component fits into a concept that is spread out over multiple files etc.
In the end code is text and like regular prosaic text you can both make it harder to understand by not mentioning things or by mentioning too many or the wrong things. This is why it is not irrelevant for programmers to be good and empathic communicators. Sure in the end readability doesn't matter to the computer, but it certainly matters to all people involved.
But of course you will have some individuals who think it is cooler not to, and they are probably the same people who think use after free bugs can be avoided by the shere willpower of the solo-male-genius that they are.
Good readable code removes the need for comments about what the code does, if the working of the code needs extra explanation then perhaps it is being too clever or overly terse, but there are other classes of comment that the code simply explaining itself can't cover.
Some of my comments cover why the code does what it does, perhaps linking it to a bigger picture. That could be as simple as a link to work ticket(s) which contain (or link to) all the pertinent details, though I prefer to include a few words of explanation too in case the code is separated from whatever system those work items are logged in.
Many comments state why things were not done another way. This can be very similar to “why the code does what it does” but can be more helpful for someone (perhaps your future self) who comes along later thinking about refactoring. These can be negative notes (“considered doing X instead, but that wouldn't work because Y or interaction with Z” – if Y and Z become irrelevant that future coder can consider the alternative, if not you've saved them some time and/or aided their understanding of the bigger picture), helpful notes for future improvement (“X would be more efficient, but more complex and we don't have time to properly test the refactor ATM” or “X would be more efficient but for current use patterns the difference would be too small to warrant spending the time” – the “but” parts are not always stated as they are usually pretty obvious). A comment can also highlight what was intended as a temporary solution to mitigate external problems (“extra work here to account for X not being trapped by Y, consider removing this once that external problem is fixed” or “because X should accept Y from us but currently doesn't”).
This is one of those blindspots devs have in that they believe their code to be good and obvious to everyone but in reality it is not even good and obvious to their future selves who will be the ones maintaining that code
That could be used to see how good a language is for specific tasks. If you need to write lots of comments, maybe you have the wrong language.
That and “those who actually use power are likely to be those who shouldn't have been given it”!
I did a survey once in about 3/4 of the comments were either wrong or useless. Examples:
//Add 1 to x
x+=1;
//Add 1 to x
x+=2;
//Seconds per normal day
x = 86400;
--
"Why not" comments are incredibly valuable except they suffer from explanatory decay as much as other comments.
The hope behind Intention Revealing Names is that the dissonance will be too great for the subsequent developers to ignore when they change the code.
Of course, that isn't always true.
x = 86400
x = 24 * 60 * 60
DAY_IN_SECONDS = 24 * 60 * 60MINUTES_PER_HOUR = 60;
HOURS_PER_DAY = 24;
DAYS_PER_SECOND = SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY
Naah.
DAYS_PER_SECOND = 1 / (SECONDS_PER_MINUTE * MINUTES_PER_HOUR * HOURS_PER_DAY) ;
> Examples:
> //Add 1 to x
> x+=1;
If 3/4ths of comments are like this, maybe show a sampling of public source code (e.g. from github) that shows how prevalent comments like this are in any real codebase.
I've been programming since 1982 and have never seen this type of "add 1 to x" comment in real code, outside chapter 1 of some intro to programming book.
I will als name each db table column in the correct order by its correct name right above that what decided the value.
// id
user_id = getUserId();
They serve as dividers.
using namespace std; // using namespace standardThat's the only reason I can think of for writing those comments.
And, you definitely had little experience with under-documented code
Also: if the code and the comments appear to disagree, there is a reasonable likelihood that both are wrong in some way.
I have regretted following that lesson ever since.