Halfway through the article: "And, of course, there are some exceptions."
I saw the title and thought this might have been some sort of hot take on self-documenting code. What I found was the same "why, not what" advice that's been repeated for decades. It's a good guideline, but nothing remotely controversial or original.
No comments by default, every comment needs to be justified. As a rule, still more reasonable than "use comments only when needed", which is more on the pro-comments side.
This whole post is based on a bad premise. Whether the reader can understand the code is dependent on the reader and not just the code.
If you're so far abstracted from hardware that none of this matters, well, OK, write what you want. But there is an awful lot of code that interacts with the hardware more directly than one might think, and even in higher level code there are often some significant gains to be had in terms of tweaking things for the branch predictors and such.
Though I guess if you're in an abstracted enough language, you can't even really influence that stuff. It's been years since I've written anything much beyond C (C++ with STL classes is a nice treat, but it mostly talks to something written in C over some data link or another).
You write code to be executed efficiently, but also to be understood (and modified) by other people.
Of course your code should be so easy to understand that comments are superfluous. But whats the problem adding the odd hint anyway?
And code alone is static, like a bridge. All the design motivations and decisions are reified, but the design conversation itself is lost. That conversation is often recorded in separate systems like github, UML, etc, but why not at least reference those systems in the code itself - until IDEs catch up and allow combined/multi-level code/comment/design/architecture/requirements browsing.
And you thought Eclipse was a memory hog now!
"Oh, yeah. IDE's down, Jira is... broken, not really down, but not really responding either, looks like they used blocking calls for that integration. You could probably null route Jira in /etc/hosts..."
"This is why we did it this way, because the more obvious methods failed in the following ways..." is certainly a good example of a use case for comments.
I tend to comment rather heavily, in the "free form" style frowned on here. However, most of my code is directly related to hardware, in some form or another, and "Assuming the person reading the code has the full hardware reference manual memorized" is simply a jerk move. There are plenty of things like direct accesses to particular memory addresses that, even with plenty of #define wrappers, are still a bit obscure unless you know what, exactly, that bit is doing. And that's before you get into weird corner cases of hardware or doing things outside the norm where even if the code is clear, it's only because you already know what it's trying to do.
It's an interesting goal and may work in a few small corners of the software industry, but having spent plenty of time sorting through what assumptions about the state of things "well written code" (which is usually a lie anyway... what's obvious to one person may not be obvious to a different person with a different background and different expectations about the code), I'll take something with a couple hundred lines of explanation at the top of the file covering the concepts the file intends to implement over bare code, any day.
Also, sometimes given teams and other requirements, a bit of an unusual use of the programming language can be explained away by a bit of ASCII art. Giving a programmer a mental model of the upcoming code can help with on-boarding new people.
A comment like “delay for 5 seconds” is bad and easily goes out of date because you might change the number of seconds in the code without updating the comment. The comment should be something like “wait a few seconds for foo the settle down” to explain why you’re doing (such a horrible hack).
I cringe when I come across a method, or a function, or a class that no comment whatsoever above it. Because it means I will have to read cryptic code to figure out how to use it. Instead a simple comment could have explained what I need to input and what output I will get.
"well written code" is largely subjective.
Even visual layout can impact performance of the individual programmer.
There should be an IDE or IDE plugin that changes how code is laid out while editing, but not in the actual code. So, it's merely a visual layer, which can be adapted to the preference of the individual. Meanwhile, the actual code is forced into a specific style too.
Constantly changing the layout of codebases is impossible and will cause people to clash. So instead, let the individual control how they see things at the IDE level on their machine.
Stop forcing entire teams into 1 single view and let everyone control their own, without altering the actual source code.
Let everyone see the code and write it as they personally prefer, and let a post-processing tool based on diffs force the changed files into a specific style for the final repository.
The industry should stop taking choice away and let everyone have the code environment they feel comfortable looking at.
I am especially fond of the way how Ruby and Ruby on Rails documents their standard libraries. Every single method (even if it is only a stub) has a comment above it that documents the method. That comment is then used to generate the documentation itself. Unit tests also ensure everything is operating as documented.
This methodology ensures that the code, comments, and documentation are all up to date and in sync with each other.
One thing to keep in mind, you don't know who is reading your code, and why. It could be someone like me, just trying to chase down a bug, or figure out how something works. I know just enough of some languages where I can usually do that much. Comments are SUPER helpful for people like me.
(yes, I realize it's a different type of "comment")
In the real world, code is based on business logic, so comments are a good place to add a ticket number (though most times a better place is usually a commit message) or a brief explanation of "why in the hell would anyone ever do it this way". Because the answer is usually something like "the client asked us to do it this way".
