3 ms·

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

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

by berntb 15y ago

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.