>> I used to think that the names of the classes, methods and variables should be enough to understand what the program does. No comments should be needed. Over the years I have realized that some comments are needed and useful.
Comments are needed where there is more to the code than just reading it. Where there is some external reason WHY. Where it is written in a specific way for non-obvious reasons. Where there are pitfalls and dangers in changing the code. Where this specific approach is the result of fixing some problem and if you change it then you might be reintroducing a problem.
There's lots of reasons to comment your code, but mostly I think code should be the documentation.
The fewer comments the better, because then developers who come later will see comments and thing "this must be important because there is a comment here". Too many comments dilutes the value of comments.
When it really matters I start my comment with a couple of lines like this:
// LISTEN UP!!!
// LISTEN UP!!!
I have to say, it seems strange that the author EVER thought that no comments should ever be needed - that seems like a strange and dogmatic conclusion to have come to.
> it seems strange that the author EVER thought that no comments should ever be needed
That was a trend many years ago when people started seeing how comments are often out-of-date, sometimes been copied pasted around so many times it's not even saying anything useful about the code next to it, and sometimes the author is just a bad writer and makes it more confusing than the code itself. So people became pissed off and kind of decided that the code needs to be clear enough to be self-documenting: short functions with verbose names, good variable names etc. making comments unnecessary.
I do agree with that, but IMHO there's still a place for comments: as many others are saying: when you need to document why something has been written that way, not just what (which the code should be able to tell by itself)... and I believe OP is also claiming that, and you appear to be missing this context.
> it seems strange that the author EVER thought that no comments should ever be needed - that seems like a strange and dogmatic conclusion to have come to.
Distressingly common, though. I'd say most of my last few positions have been at places where "self-documenting code" was the mantra even though it was blatantly clear that the code and what it was doing was far too complex for that to work.
That gets me thinking, if the code is obvious enough it doesn’t need comments, is it useful code? Like in an ideal world, all the “how” is transparent and we’re left only with the juicy bits, that explain / define business needs.
I’ve noticed that different language have various ideas about this - like
Closure would be close to a fetish to build abstractions so that the actual code that does “stuff” just explains the business process, and the rest are just libraries.
Or golang goes in the other extreme where there it is idiomatic to have as little abstraction as possible, writing up everything as you go.
Haven’t coded much in either so this is just a beginner’s observation.
Programming language generations may be relevant here if you are interested. Prolog for example can be called a 5th generation PL, which means that you state what you want instead of how you want it achieved. Wikipedia lists SQL at the 4th gen, though I think the former is just as true for SQL as well - you only state that you want this and that row/field, and the actual algorithm is up to the query optimizer.
> it seems strange that the author EVER thought that no comments should ever be needed - that seems like a strange and dogmatic conclusion to have come to.
But just before that you say:
> There's lots of reasons to comment your code, but mostly I think code should be the documentation.
Exactly that's why it's not at all strange. As you yourself write, code should be the documentation. Need to add comments => your code is unclear, and unclear code => bad code, and so instead of writing comments your time is better spent improving the code.
The reality of course is that things need to be done and there's no time to fix all layers and have perfectly organized and readable code and therefore clarifying comments are needed.
So no need to shame the author, it's just a typical progression from youthful maximalism to more mature shades of grey thinking.
I think the "never use comments" trend came from folks who'd realised "comments lie, code never does".
E.g. developers might forget to update comments when they fix a bug.
There are also the "// set b to 0" brigade, which is an exaggeration but makes the point that commenting the painfully obvious is a trap too many fall into.
I think there was also an argument that methods called "setWidgetsToMaximumSoThatStartOfDayChecksWorkOnWeekends()" were a Good Thing, and definitively Self Documenting, a viewpoint which seems (thankfully) to be losing popularity.
Comments are needed where there is more to the code than just reading it. Where there is some external reason WHY. Where it is written in a specific way for non-obvious reasons. Where there are pitfalls and dangers in changing the code. Where this specific approach is the result of fixing some problem and if you change it then you might be reintroducing a problem.
There's lots of reasons to comment your code, but mostly I think code should be the documentation.
The fewer comments the better, because then developers who come later will see comments and thing "this must be important because there is a comment here". Too many comments dilutes the value of comments.
When it really matters I start my comment with a couple of lines like this:
I have to say, it seems strange that the author EVER thought that no comments should ever be needed - that seems like a strange and dogmatic conclusion to have come to.