Comments only lie if they are allowed to become one.

Just like a method name can lie. Or a class name. Or ...

The compiler ensures that the code is valid, and what ensures that ‘// used a suboptimal sort because reasons’ is updated during a global refactor that changes the method? … some dude living in that module all day every day exercising monk-like discipline? That is unwanted for a few reasons, notably the routine failures of such efforts over time.

Module names and namespaces and function names can lie. But they are also corrected wholesale and en-masse when first fixed, those lies are made apparent when using them. If right_pad() is updated so it’s actually left_pad() it gets caught as an error source during implementation or as an independent naming issue in working code. If that misrepresentation is the source of an emergent error it will be visible and unavoidable in debugging if it’s in code, and the subsequent correction will be validated by the compiler (and therefore amenable to automated testing).

Lies in comments don’t reduce the potential for lies in code, but keeping inline comments minimal and focused on exceptional circumstances can meaningfully reduce the number of aggregate lies in a codebase.

And for that matter, what ensures it is even correct the first time it is written?

(I think this is probably the far more common problem when I'm looking at a bug, newly discovered: the logic was broken on day 1, hasn't changed since; the comment, when there is one, is as wrong as the day it was written.)

Go ask Steve, he wrote it, oh, he left about 3 years ago... does anyone know what he was thinking?

I <3 great (edit: improve clarity) commit comments, but I am leaning more heavily to good comments at the same level as the dev is reading - right there in the code - rather than telling them to look at git blame, find the appropriate commit message (keeping in mind that there might have been changes to the line(s) of code and commits might intertwine, thus making it a mission to find the commit holding the right message(s).

edit: I forgot to add - commit messages are great, assuming the people merging the PR into main aren't squashing the commits (a lot of people do this because of a lack of understanding of our friend rebase)

Or do you think that your example comment brings knowledge other than "I want you to know that I know that it is not optimal, but it is fine, so don't judge me"?

Over the years, I have seen many, many juniors wrapping simple CLI invocations in a script because they just learned about them and thought they weren't obvious.

- clone_git_repo.sh

- run_docker_container.sh

I do agree that something actually tricky should be commented. But that's exceedingly rare.

Someone following me could look at it and go.. "well duh" and that's not going to hurt anyone, but if I didn't put that comment and someone refractometer, then we have someone redoing and then undoing, for no good reason.

There's that meme where people are told to update the number of hours wasted because people try to refactor some coffee and have to undo it because it doesn't work

Obviously you don't, because you assume that the person reading that code has some level of knowledge. You don't say "well, it may not be obvious to everybody, so I need to explain everything".

I guess where we differ is that to me, a professional software developer should be able to understand good code. If they aren't, they are a junior who needs practice. But I am for designing tools for the professionals, not for the apprentices. The goal of an apprentice is to become a professional, not to remain an apprentice forever.

Thank you for missing the point.

It's not about the WHAT, it's about the WHY.

For loops are obvious. O(n) being intentional instead of 'lazy' isn't obvious without context. That's what comments preserve - the decision rationale, not the syntax explanation.

A professional developer can read code. But they can't read the mind of the author who made a non obvious tradeoff. That's what comments preserve.

> I guess where we differ is that to me, a professional software developer should be able to understand good code. If they aren't, they are a junior who needs practice. But I am for designing tools for the professionals, not for the apprentices. The goal of an apprentice is to become a professional, not to remain an apprentice forever.

If you are going to make personal attacks, you should know that I work with actual professionals, and they understand that future maintainers, myself included, cannot read their mind on why they chose the path they did.

And my point is that I don't care what it is about, I care about whether or not it is useful. I disagree with the literate programming idea that it's always useful to explain why you wrote the code the way you did, and your one example (justifying the O(n)) actually proves to me that I really don't care about your explanation in this particular case. So obviously your one example that I don't find useful won't convince me that all WHY comments are useful.

> O(n) being intentional instead of 'lazy' isn't obvious without context.

What does such a comment tell me?

- That you chose the O(n): it's the "please don't judge me, I know what I am doing" part. It's superfluous, because by default I assume that you know what you are doing.

- That you tried to do better and failed. If I believe that we don't need better than O(n), I don't care. If I believe that we need better than O(n), I will reason about doing it myself (no matter what you wrote).

- ... I can't see anything else.

Now sometimes, of course, there is real knowledge that needs to go into a comment. Like "This is a workaround due to a bug in version 1.4.2 of this proprietary dependency". But that's an exception. I can also totally imagine that some files implement something really tricky and deserve a lot of comments. But in my experience reading and contributing to a lot of open source code from many different projects, most code is not like that. The concept of "literate programming" doesn't say "be pragmatic about comments, use them when it matters", it says "comment the code because it always helps".

> If you are going to make personal attacks

I am not making personal attacks, I genuinely believe that you are perfectly able to read and understand code that does not follow the "literate programming" paradigm. And if you are not, I still don't see that as a personal attack: with experience you will definitely get there.

> cannot read their mind on why they chose the path they did.

I just want to repeat it here: it does not matter at the implementation detail level. You may want to document the architecture (including technology choices) of course, but that's not what literate programming is about. You probably want to document the public API (because using an API generally does not require reading the code, and the implementation may be proprietary), but again that's not what literate programming is about. But the implementation details? Unless it's surprising (e.g. a necessary workaround), I don't care about why it was written the way it was, I just care about understanding what it does such that I can reason about it.

And maybe also that you don't seem to make the difference between natural languages and programming languages: I have not been commenting code here. If you can't make the difference, maybe it explains why you want to mix them.