It's a hyperbolization prop (frame from a classic movie where main character is as passionate about small things as an individual can get, to the point where it even looks ridiculous)
Thank you for this reference, title of the article is merely an attempt to adapt/paraphrase a famous quote, it's not at all literal (absolutely no comments ever allowed)
Now that I know, I think it's funny (well, darkly funny). However, while I do have the context for that quote, I had never actually seen the scene or stills from it, so I didn't realize it was a reference, so the title put me off as well.
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.
While the title is a bit off, the sentiment is still valid.
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.
I wonder if people are unwittingly conditioned by the situation at newspapers. Where the writer doesn't choose the headline...the editor does. So they get used to the pattern of headlines that don't align with the content. And then do it to themselves.
People act as if they are great communicators with their code. Most developers are terrible communicators in person/text so even worse using a language. Having comments plus readable code is nothing but a net-positive.
Found during the rabbit trail this sent me down. Sounds like something most of you already knew about, but I didn't. So, sharing on the off chance it's also new for someone else.
Sometimes given the technology or interface, its necessary to tell the next poor soul what is going on. Anyone who has wrote code to interface with an external system knows the story of odd interaction requirements that need to be document for the person who is maintaining the code at the point of use.
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.
The “exception” section pretty much describes why you should use comments. The other examples are just bad comments.
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 would disagree, it's all about time spent (one can argue wasted) It's a lot faster to "get", to understand well written code that uses natural language semantics regardless of the reader competency
"To understand this code, first understand the entire Intel SDM, volumes 1 and 3, using 2 and 4 as needed to clarify MSRs, with chipset documentation added as needed for hardware specific MSRs" is far, far harder than some comments in each section briefly describing the hardware section being interacted with, and what particular bits do.
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).
And someone will then have to puzzle through what they assume is "well-written code" to work out what broke when things failed...
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.
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".
Al these comment/no-comment articles are a little precious.
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.
> 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.
Code should document itself... yes, and if someone who knows the language is reading the code, that probably works pretty well most of the time.
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.
I think the OP is describing an abstract ideal, but not something that bears out in practice. When navigating old code, or very large code bases, or code weighed down by technical debt, or mathematically complex code, or just poorly/hastily written code, finding a comment describing a method's intention provides valuable context.
> Don’t we cringe a little every time we come across a method, or a function, or a class that has a lengthy, freestyle comment above it?
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.
The only thing better than well written code is well written code with well written comments.
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.
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.
30 comments
[ 5.2 ms ] story [ 70.6 ms ] threadHalfway 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.
(yes, I realize it's a different type of "comment")
https://mcfunley.com/from-the-annals-of-dubious-achievement
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).
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).
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.
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".
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.
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.
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.
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.
"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.