Plain code organized into understandable methods (usually no more than half a page of code), with good naming for variables & method names reduces the need for comments.
It's also easier to scan/read code if there's a minimum of comments in the way.
Clear, self-documenting code is great but it can't capture that holistic insight into what the whole program is doing. It can't capture context, because the whole point of clean refactored code is to be as context-free as possible.
As an example, our code base has a comment which refers to our internal issue tracker which itself refers to this HN comment: https://news.ycombinator.com/item?id=9048947
I was secretly hoping you actually meant your own comment, creating a recursive loop. But a surprise John Nagle is even better
Or sometimes, not even that: issues elsewhere in the system, possibly completely outside of your control (e.g. the language/framework/library you're using, the OS, business requirements, etc).
Code shows what is being done. Comments should explain why it's being done.
Often you have horrible complexity imposed on you from outside -- business rules you're implementing, etc, which are _not simple_. You can write code that encapsulates a lot of that, and even refactor it so you can see _what_ the code is doing pretty easily ... but it's often _very_ valuable to document in a code comment (docstring, JSdoc, etc) WHY it's like that.
Arguably, the comment is not to explain the code, in this case, but rather to explain the twisted bureaucratic logic you're having to implement, so maybe that still counts as "brilliant" code. ;)
I look back at a lot of my old code and even without comments, it's easy to follow the logic because I used sensible names and constructs.
Often it means you can refactor it so that there is only one of any "thing" so there is no need to clarify which version or role this "fooBarThing" is serving to disambiguate it from the other "bazBarThing".
Functional composition and well structured data is the key to this. It's basically halfway to point-free style.
Readable variable names doesn't mean wordy names. I would avoid using more than 2 words in a variable name.
You're lucky if you're dealing with code that's either small enough or simple enough not to need the added context...or if you only need to read your old code.
Documentation explains HOW to use a thing. Good comments explain WHY a thing is strange. Bad comments explain WHAT a thing does and must be made redundant by extracting and naming the thing.
Probably overly generalized to be pithy, but no.
Comments are by very definition documentation, which can and should cover of all of the what/why/who/how/where.
Documentation that occasionally explains how to use code can actually be useful!
Unless you actually get around to writing a user manual (which gets out of date), please do consider documenting how something should be used, particularly in libraries.
Also, i never said documentation isn't useful. HOW and WHY are useful. WHAT in documentation and comments isn't because it should be in the variable/function/method/class/instance name.
(Who/Where/When are covered by the source repository and the blame function.)
Moreover, when the weight of those comments trends towards 50% being justifications for why you did it that way, it's an excellent sign that your code has gone from "brilliant" to "super-genius", as in "Wile E. Coyote, Super-Genius".
"Completely dumb" code can be read by your future self without comments. Even, sometimes, by other people!
But for the general case, I do wholeheartedly agree with you.
That's like saying "the problem with healthcare is that it costs money". Of course comments can get out of date. The solution isn't to throw them out!
There's alternative to in-code comments answering the question "why" - it's commit messages. They can't be out of date.
git log -L0,10:file.txt
Write good commit messages and comments that answer "why" are redundant too. Commit messages by their nature refer to the exact code that they refered to when they were written. Comments answering "why" after a few years are misleading anyway, because code changed around them.
Commenting public api etc is obvious, and most people do it.
If there's not 1 line of code from that commit remaining why is it relevant?
If something looks weird still - I go back to the commit that created this part of code and git blame that. I don't remember a case where I had to do 2 steps like that.
BTW we have a rule of putting JIRA ticket numbers in commits, that makes it even easier to find out. You can see the whole discussion that resulted in the code you try to understand, test cases that you don't want to break with your new changes, etc.
sounds great until there's a refactor (including moving code around), then all the "comments" get buried.
So something entirely outside the codebase, which may or may not be available to the person who needs the information, and which may or may not need to be extensively searched through years of history to find the relevant commit message, which may or may not be sufficient to explain the code... is better than having a comment in the code.
The vast majority of comments I usually see can be rolled into variable names or function names. If you're writing lots of comments, that's a good indication your code is hard to understand, your variables are badly named and your functions are too long in my opinion. I think people that say "your code is bad if you don't have any comments" have things backwards personally.
Pretty much the only time I use comments is when I'm forced to write weird code to workaround an API bug, to explain an unintuitive optimisation or to give high-level architecture documentation.
I've honestly returned to code I've written myself maybe 5 years later and rarely had an issue that would have been helped with more comments.
That should leave you with a solid documentation of your application's components and APIs and a small amount of inline comments.
If you find you have more comments, either your code should be simplified or you're commenting trivialities.
As everything, it's a guideline with exceptions, not an absolute rule.
Likewise, your future self will hate you when comments fall out of sync with the code.
If the code is readable you don't need much in the way of comments.
Unless you are writing completely brilliant code your future self will hate you if you skimp on comments. Also self-documenting code is great, but intentions are not always clear to another person trying to figure out your code.