4 ms·

My first thought was: "oh my God, I'm a n00b!" My second thought was: "no, I just think I disagree with him". Comments in the code are good. They help the nex

by wulczer 15y ago

My first thought was: "oh my God, I'm a n00b!" 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/tcop/postgres.c#L789 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?

berntb 15y ago
>>... I disagree [...] Comments in the code are good. 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"? :-( :-) )
- joske2 15y ago
  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,..)
- nupark2 15y ago
  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.
  - berntb 15y ago
    Well, you're right. 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 :-) )
    - Meai 15y ago
      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.
majmun 15y ago
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.
- DougBTX 15y ago
  > I don't like it because you can't see big picture but must scroll up and down until you understand. In a large code base, I doubt you'll be able to get a "big picture" view from any one file.
  - majmun 15y ago
    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. :-)
- VMG 15y ago
  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.
- jtchang 15y ago
  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.
- pivo 15y ago
  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.
_delirium 15y ago
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.
- bborud 15y ago
  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.
  - Roboprog 15y ago
    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.
ShirtlessRod 15y ago
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".

by wulczer 15y ago

berntb 15y ago

>>... I disagree [...] Comments in the code are good. 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"? :-( :-) )

joske2 15y ago
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,..)
nupark2 15y ago
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.
- berntb 15y ago
  Well, you're right. 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 :-) )
  - Meai 15y ago
    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.

majmun 15y ago

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.

DougBTX 15y ago
> I don't like it because you can't see big picture but must scroll up and down until you understand. In a large code base, I doubt you'll be able to get a "big picture" view from any one file.
- majmun 15y ago
  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. :-)
VMG 15y ago
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.
jtchang 15y ago
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.
pivo 15y ago
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.

_delirium 15y ago

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.

bborud 15y ago
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.
- Roboprog 15y ago
  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.

ShirtlessRod 15y ago

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".