Agree with most of what you said, except on the __impossible__ part.

You can tell everything with code, given enough time and resources. Nothing is "impossible". But there's a point where you hit diminishing returns. It's about efficiency.

Other devs, or your future self, will have to time trying to build the same "castle in your head" as you did. Can a comment shorten that time? If a one-line comment saves 15 minutes of investigation in aggregate, that's a no-brainer. You should add it. Conversely, a line that says "add 5 to x" is just wasting everyone's time.

As a general rule, once I have finally understood a particularly hairy piece of code, I don't want to do it again in 6 months. I have even done ASCII diagrams in the comments explaining how a particularly hairy piece of code worked, when I hated it enough.

ASCII diagram comments are surprisingly common in scientific computing, FWIW. It's not so much that it's always hairy code, more that it helps to add some visualizations of what's going on. Math vs intuitive understanding are often very different things.

It's something I wish was more common than it is. Sometimes you really want that ASCII pseudo graph explaining how minimizing this thing relates to that other thing that we actually care about.

Taken a step further, I really wish we had better systems for managing this type of information alongside a codebase. E.g. the whitepaper, or presentation, or figures, or whatever is often very necessary to understand the code, and ideally it would be under version control and live neatly alongside things. Nicely rendered docs definitely help with this (e.g. latex in comments), but I'm always surprised there aren't more people focusing on this aspect of information management.

In my experience, one man’s “waste of time” is another man’s castle-in-the-head-building-time-saver. At my current company, if I have reasonable, self explanatory code, such as a function with the signature “read_page(page_num: u32) -> PageData”, they’ll gather it reads a page with the given page number and extracts the data. At my last company, if I wrote the same code, I’d receive a comment on my PR complaining I did not document it will enough. I would then add a comment that somehow only I was able to detect was snarkily written, something like “// reads the given page number and returns its data” and they would be happy as clams.

I always assumed that behavior was dogmatic until, over many PRs, multiple members of the team commented that if I commented my code, it would be much easier to read. And comments of the above quality assuaged them.

What I would miss, in the above, is information about:

- where the page is being read from

- what page numbers the function accepts

- what happens if an invalid page number is specified (or if that’s deliberately undefined, stating that fact)

- other possible error conditions, if any

(I’ll assume that PageData already documents what “page” refers to in that context, because for me it’s not “self explanatory” just from the function signature you provided.)

> You can tell everything with code, given enough time and resources.

That's just not true.

There are infinite many ways to write the exact same thing.

Your code can never say why it's like it is, why this approach was chosen and not another.

> […] the comments explaining how a particularly hairy piece of code worked […]

This kind of comments are the bad ones actually.

Your code should be clear enough that it's easy to see how it works and what is happening.

The rule is actually very simple, and I don't get it why so many people have issues with following it.

"Code says what and how, comments say why."

> The rule is actually very simple

Why does there have to be rules about when to comment? I comment frequently about whatever the hell I want. Don’t like it? Then don’t read the comments. Very simple, just like your rule.

Useless comments are like useless code: They create an unnecessary (and therefore costly) maintenance burden.

If you think you're the smartest person on the planet so "rules" (or better said best practices) don't apply to anything you do I hope nobody ever needs to collaborate with you.

All the "rules" are there for a reason!

No, you're not free do to whatever you like in a professional setting. For example when you're operating machines you need to follow safety regulations. Otherwise you could even end up in jail quite quickly.

> All the "rules" are there for a reason!

Except in this case, you've made up the rule. It is not an axiomatic rule like gravity. I want different rules. So unless we work together, your rules don't apply to me.

> There are infinite many ways to write the exact same thing.

I agree with that. I don't think that makes things impossible. Only more difficult.

> Your code can never say why it's like it is, why this approach was chosen and not another.

If the why is important, given enough time and resources, someone will eventually complain that something is not working and someone will be tasked to "fix it". It may take them weeks, but they will eventually figure out the why.

> Code says what and how, comments say why.

If we are considering only quality vs quality, I agree. But there's also quantity.

When the how is complicated enough, it is indistinguishable from a why. You will hear the reviewers ask outloud: "But WHY is this done this way?". Even if the problem is merely algorithmic/technical and the code is doing exactly what it's supposed to do.

Then you have two options: spend a potentially significant time refactoring things (which is always the right choice, given enough time and resources) or spend 10 minutes writing a comment with what you learned, and moving on to the next problem.

I wish I could get this point across to my team. They will happily write:

db.insert(record); // save the record to the database

But when they write some crazy off-the-wall code (that's usually because they didn't understand the proper way to do something) I have to check the logs to see who wrote it and ask them why.

Just the other day I was debugging an application that had a 6 second sleep at the end of the main() function. I just figured it was some dumb thing left in for debugging and deleted it, because there's no good reason to do that. The next day, the dev who put it in messaged me and said he put it there because the application was exiting before it had logged it's completion to our logging system. So I explained that the proper way to do this is to flush the log, not just hang the application for 6 seconds so that the last messages just happen to go through.

If there was a comment explaining why there was a 6 second sleep, I could have just fixed it and educated the developer without causing any grief.

thats a legit case of, "its impossible to gleam that fact from the code and the code alone." (although I would have left that as a comment for the reviewer in the PR) so if theres a conversation around that decision, it would have been captured there.)

The discussion in the PR does not help the next guy…

All why answers belong into the code, as comments.

> I just figured it was some dumb thing left in for debugging and deleted it, because there's no good reason to do that.

Look up Chesterton’s Fence. :)

(I made similar errors more than once.)

You should be very careful applying Chesterton’s Fence to software engineering. Oftentimes the knowledge why fence exists is more valuable than the fence itself. And the best way to (re-)obtain this knowledge is to remove the fence and see what breaks.

I've seen people get stuck for months being afraid to change a complex piece of code because nobody understands how it works anymore. The best course of action was to admit that knowledge is lost forever and the fastest way to gain it again is to repeat past mistakes.

Of course, don't do this if your software is responsible for landing airplanes. But most of us are not landing airplanes here.

When you look at the original quote [0], it doesn’t necessarily disagree. You’re free to test what happens when removing the code, and when it then breaks you’ll know why the code was there, and can then decide what to do. However, when everything still seems to work after removing it, that is dangerous, because you’re likely to overlook some edge case or some unconsidered use case that may come back to bite you later.

Of course, Chesterton’s Fence is just a guideline. You can weigh the risks against the benefits in each case. It’s just a reminder that there may well be very good reasons why some logic is in place. If it is at all possible to find out those reasons, then that would generally be preferable, in order to make an informed decision.

[0] https://en.wikipedia.org/wiki/G._K._Chesterton#Chesterton's_...

> that is dangerous, because you’re likely to overlook some edge case or some unconsidered use case that may come back to bite you later.

I know, and that's exactly why I don't like it. In my experience, lack of understanding bites you way harder than lack of a single fence.

I once worked at a company that had a very complicated patented (!) algorithm to calculate a certain value. Not a single person in the company knew why it was so complicated, and nobody ever questioned it. We would constantly struggle to introduce new rules to it, because they would conflict with the old rules, and it wasn't clear how to resolve those conflicts.

Since we didn't understand what value those magical rules provided, there was absolutely no way we could resolve conflicts in a way that retains the original value (if there was any).

Eventually I was able to convince everyone and just removed all the rules we didn't understand. Everyone sighed with a relief.

In hindsight, I believe the sole reason algorithm was so complicated was that having a patented algorithm would sound more sexy to investors, and you can't patent something stupidly simple.

+10

Throwaway commenting often makes people feel as if they’re adding value, whilst fulfilling their obligations.

Of course such comments have no value and worse, can distract from what ought to be commented.

Perhaps ChatGPT has found a use, if it is asked to add comments to code, although I somehow doubt it…

Interesting paper, thanks for posting. The paper goes on to say:

> One should take care not to overestimate the impact of language on defects. While the observed relationships are statistically significant, the effects are quite small. Analysis of deviance reveals that language accounts for less than 1% of the total explained deviance

Comments are critical at creating beginners to the code base, something rarely the expert class think about accelerating.

For my code? I agree

Code for others to participate in? The simplest possible way for the greatest number of developers to understand as quickly as possible. Not about my best practice or preference but for the greater good.

Coding standards for the elite devs are only so effective at growing that growing quick enough.

The expert will be helped as well when coming back to the code after a few months.

100%.

Comments are a critical way to more quickly re-grok the mental model of what's going on for your future self as well.

I think there was a post in the past few weeks about a single developer who maintained hundreds of his own tools, and for him it came down to process and documentation first so it was easy to come back to months or years later.

Where are Ada and Rust mentioned in that link? The top listed down to Ruby in that link by general failure seem to be: Scala, Perl, Clojure/PHP (tied), Haskell/Go (tied), TypeScript, Ruby.

The Ruby community has a very good culture of testing application and framework code, but in my experience is quite poor at properly specifying behaviour or writing truly robust code.

Many functions in the standard library behave subtly differently from there documentation or have behaviour that is not documented but depended on by applications, and I’ve certainly seen lots of concurrency bugs in both code and tests because the GVL makes it hard to provoke the worst case behaviour.

The unit tests are really useful for Ruby language implementations because they help give us confidence we’re replicating all the required behaviour, but from that point of view I wish the underlying things were better specified so those tests weren’t quite so necessary.

Don’t get me wrong. I love Ruby as a language and loved working on TruffleRuby, but I don’t think the community should be too smug about code quality and testing.