Why don't you write comments describing what the code does?
> and even they often don't know because... surprise... nobody wrote anything down!
Well, read the code
And who mentioned writing comments only about intention?
> Why don't you write comments describing what the code does?
Yes, why don't we?
> Well, read the code
Because code is never long and vague, and human language can never sum up complex ideas or code?
> It wouldn't kill us to just write some documenting comments detailing the intention behind code
Intention behind the code != Describe the code
> Because code is never long and vague, and human language can never sum up complex ideas or code?
No, code isn't vague, and hood code mostly it isn't long.
Variable names are human language btw. A programming language is a human language.
Where are you getting this exclusivity from? Given your use of an equality operator, maybe you're thinking in code a bit too much.
> No, code isn't vague, and [good] code mostly it isn't long.
This isn't even remotely true. There are many dimensions to code that a human might subjectively use to determine whether code is "good." Code that is "clean" can often be a performance nightmare, but code that someone subjectively claims to be "unreadable" can be more performant, more fault resistant, future proof, and so forth. In the context of human interpretation, code can be vague regardless of how "good" that code seems to someone.
Also, the mere fact that anyone can disagree with you that good code "mostly" isn't long discredits the very idea in an objective sense. Plenty of programmers don't care whether code is "long" if it's written procedurally and/or with pure functions. If you haven't heard such opinions before, then you need to meet more programmers of varying disciplines.
> Variable names are human language btw. A programming language is a human language.
A programming language is for the benefit of both the human and the machine, though it's still mostly to the benefit of the machine. If it were solely a human language, then it would be closer if not identical to a language like English. And, if it were, it would be tremendously slow relative to traditional programming languages, and even generate more waste heat.
At the same time I believe that there are a few objective metrics that seem to correlate with long term maintainability of a codebase. For example, the more contextual, relevant, and correct(!) information it contains, the easier it is to work with the code, especially once the original authors depart (and they will, sooner or later). Capturing that information and putting it in the code - in whatever way, including comments, diagrams (ascii art and graphical), particular tests and doctests, explicit pre and postconditions, other assertions, log calls - lowers the effort needed to maintain said code.
If the additional information threatens to obscure the the view on what's actually happening, you can refactor it the same way you'd refactor code. If you can introduce helper functions to kick details out of the way, you can also add footnotes and links to files with additional docs to get the level of detail manageable in the most often read code, while still providing enough information about that code.
What do you think? I came to this conclusion based on my experience with learning a very diverse set of programming styles and languages, experience with maintaining long-lived projects at work, and the "Programmer's Brain" book. The book has its moments, though for the most part it's just boring, but it did provide me with a few puzzle pieces I needed to make some sense out of the whole thing.
Take his views on "clean code" for instance. Or really any conception of "clean code." Clean code is bullshit. I guarantee you can take anything Uncle Bub or other notable programmers say about clean code, apply them to a tee at your job, and be told that your code isn't clean or "feels icky" by whomever joined the team before you did. No description of clean code that I've read has ever been truly helpful in my career. The only thing you can really do is decide what you think is clean code and for you and your team to reach a level of agreed disagreement so that everyone can get their job done. One person's descriptive variable name is another person's "that's too long I can't read with all these confusing names", and one person's set of short purposeful functions is another person's "I can't tell what's happening cuz I have to jump between all these functions." At the end of the day, you barely have time to write "clean code", because your boss wants features rolled out ASAP.
Uncle Bub is also one of those guys who thinks good code doesn't need comments because it's self descriptive. This is one of the worst ideas to ever have met the software industry. No one's code is self descriptive. It's all a bunch of gobbledygook because it's meant to be run by a computer and just understandable enough for a human. It wouldn't kill us to just write some documenting comments detailing the intention behind code, but sadly most programmers either are too lazy or believe that if they need to add comments then that necessarily means their code smells. The result is that nobody knows anything about any given software project except for those who have been on the project the longest, and even they often don't know because... surprise... nobody wrote anything down! Just like with "clean code", it should be left up to teams how they want to add comments to code, and how much you comment your code shouldn't be influenced by memes from other programmers.
Don't even get me started on FrAgile. It's just a way to dupe programmers into taking on more work and doing the job of middle management for them.