4 ms·
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
by 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 agoWell, 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 agoYes 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.