Of course, literate programming doesn't advocate writing completely trivial English explanations, so they agree on the counter++ case, but it sounds like Yegge opposes a large ratio of explanatory comments more generally.
I've worked with a lot of different programmers over the years. Some are capable of "running" large pieces of code in their head, keeping track of state transitions. Some need a more structured approach so they can concentrate of fewer moving parts at a time. I can to some degree keep lots of code in my head, but I know that the chance of mistakes increases when I do. It is a useful skill to have, but an exhausting and error prone way to work, so I prefer not to.
When I read my own code, I don't really read it as such. I scan it. Often can often look at just the silhouette of a paragraph, a method or even a class to be able to tell you what the code does. I tend to do "one thing per paragraph" -- which when I read code means that I can skip past the code I am not interested in at the moment quickly.
I often notice how other people actually read code, and it makes my skin crawl. I can't watch. It is so SLOW.
Yes, getting more code onto each screenfull is great -- but not having to read the code will always be faster.
Make the routine/function so that it indeed does one thing, and you can tell what the inputs and results are. Should you ever need to debug, you can check the data and avoid the internals until you know that this is indeed the broken routine.
Contrast with the mega-routines that one of my former coworkers calls "stir the pot". Those are just broken by (lack of) design, and no commenting strategy can really fix.
(It is important to know when you are documenting the API and when you are saying something about the underlying implementation -- and what you should say. Again, the goal is to anticipate what will help your users or maintainers that come after you do the right thing).
Occasionally you will need to make some comments regarding the implementation, and I usually make those comments at the start of a code paragraph. Usually to clarify intent when the intent can be misunderstood (to counter "I know what the code does, but not what it tries to accomplish").
Keeping methods short is a good thing, but I'm not dogmatic about it. Though I am allergic to long methods; occasionally there are methods that become even harder to read if you chop them up into lots of small bits. In that case guard-based programming and making use of paragraphs in your code really does help.
And human tends to put ambiguous comments. so i just don't read it if i don't have to.
Comments that contains examples of input and output, current state of variables can be helpful. or things like that.
So more compressed code is ok, because it has more data displayed in more convinient form. It is same thing for displaying other kinds of data besides code.
But i may also be n00b. so take this with grain of salt.
In a large code base, I doubt you'll be able to get a "big picture" view from any one file.
I also think that some of those functions are too large even without their comments, exec_simple_query is gigantic.
In all but very specific circumstances, the "what" should be fairly obvious by reading the code, with small clues being sufficient to guide the reader.
However, without any comments then there is no way for the reader to understand why a particular approach was chosen. Worse, they may think it needs to be refactored, and then waste time pursuing that only to arrive at the all-too-familiar "oh, that's why they did it that way".
Read the elisp example after "In contrast, here's what my code tends to look like today:"
I doubt Yegge argues against well written comments.
(Personally, I wonder if I should start to sign everything I write with "/eternal teenager"? :-( :-) )
The elisp example is impossible to skim. No comments, no breaking up of independent operation blocks. I'd say this is terribly commented code.
I'd be annoyed to have to work with it in any quantity: understanding it completely requires reading all of the code, in detail, rather than being able to trust the comments to define the input/output and pre-conditions/post-conditions of the interior blocks of related code.
I'm not a "n00b", and personally, I'd define a "n00b" as someone who doesn't understand the importance of documenting invariants. Said "n00bs" usually have trouble reasoning through all of the otherwise implicit invariants of the code they are writing, and don't understand the importance of doing so.
The PostgreSQL code example above is fantastic. Steve Yegge's code is ugly as sin. PostgreSQL is also one of the most dependable/reliable/well-maintained pieces of software I've used.
Personally, as long as the tests worked, I'd just read the documentation string. (My gut reaction of happiness to see a doc string probably means that I should update my CV. 1/2 :-) )
My second thought was: "no, I just think I disagree with him".
Comments in the code are good. They help the next person that touches that particular part of the project understand why it's coded as is and why it wouldn't be a good idea to code it differently. Commenting a counter increment with "increment the counter" is silly. Commenting it with "it's safe to increment it without taking locks, because the caller already took them" is useful.
The most beautiful codebase I've ever seen is PostgreSQL and the comment density in its source tree is quite big. Take a look at https://github.com/postgres/postgres/blob/master/src/backend...
Would you say that this code has been written by a two-year-old? Or rather that it's been written by a responsible adult that cared about the integrity of future coders' tonsures and wanted to save them some heavy head-scratching?