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.
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?
Knuth would probably disagree with him also; Yegge's post is almost an anti-literate-programming manifesto, opposing the idea of interspersing your code with English explanations of what it does and why.
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 think that Yegge might have been somewhat inspired by a programming style that was widespread in Google at least when I worked there: get as much code into each screenfull as possible.
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.
Put the comments above the routine, and try to keep the routine statements/expression/code to about one screenful of code (give or take, needs vary).
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.
This depends a bit on the type of comment. If we are speaking Java or something that uses the method comment to generate documentation, the documentation comment should not concern itself with implementation detail. However, documenting all pre- and post conditions as well as any side-effects is a good thing.
(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.
I don't like it (PostgreSQL example) because you can't see big picture but must scroll up and down until you understand.
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.
I find the PostgreSQL example great. The big picture is given to you by the function comment. Scrolling is just a side effect...you can get around it by a good IDE.
yep true, but i meant "big picture" of that particular function, poor choosing of words. but it would be more cool if you somehow would be able from one function see big picture of whole project like in fractals or some thing. :-)
I'm pretty sure that if I were to start contributing to that codebase I'd be really happy that those comments where there. However I'm also pretty sure that as I learned the code I'd be less happy about them and prefer to be able to see more of a function on a single screen. So maybe n00b-hood applies to code bases too.
I also think that some of those functions are too large even without their comments, exec_simple_query is gigantic.
It is also worth noting that comments have less contrast on github and in most other IDEs. I think it speaks to the fact that humans and computers actually care about the same parts of the code file.
I don't think this point can be emphasized enough. When you comment code, your primary focus should be on the "why".
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:"
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 :-) )
Yes and that is exactly the point of comments: to make reading code as unnecessary as possible. The base assumption (and reality) should be that every function is working perfectly. People who criticize the existence of too many comments seem to want to read code too often.
I honestly thought the elisp example code looked pretty bad as well. I don't like the flag-style programming (in-for, continue, destructuring) nor do I like the meaningless names (tt, s, init, continue, js2-lb,..). That one function also has quite a lot of responsibilities (looping while you see commas, error handling, handling simple, destructured and in-for vars,..)
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?