6 ms·

Portrait of a N00b

124 points by nyellin 15y ago

DanBC 15y ago
> If it's a complicated algorithm, a veteran programmer wants to see the whole thing on the screen, which means reducing the number of blank lines and inline comments – especially comments that simply reiterate what the code is doing. Don't text editors have, along with syntax highlighting, any "hide comments" and "compress whitespace especially blank lines" features?
- __david__ 15y ago
  Possibly, but those are actually kind of dangerous, because if you have the comments hidden and you are editing the code you probably aren't updating the comments. And stale comments are worse than no comments.
  - ajross 15y ago
    Absolutely true. But your assumption that people being able to read comments means that they'll update them seems awfully naive. Comments become lies over time. They always do.
    - __david__ 15y ago
      I didn't mean to imply that and I completely agree with you. I'm not a huge commenter myself--my general rule is only comment what is weird or un-obvious and make the code readable with good function and variable names.
dirtyaura 15y ago
I like this one: "when in doubt, don't model it."
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.
rheide 15y ago
The narrative commenting style was particularly recognizable. I started out in Java ~8 years ago and only recently moved to Python. Whenever I used to write a particular algorithm in Java I would write comments in the narrative style described by the article. However, I noticed myself deleting large chunks of those comments as I revisited the code at a later point in time. Comment refactoring, so to speak. These days, in Python, I rarely write narratives, and when I do, I delete or shorten the narrative before I commit. Moral of the story: narratives can be useful to organize your brain, even with years of experience, but they should really be gone when the code (and your thought process) is finished.
deleted 15y ago
[deleted]
buro9 15y ago
Both fail for me. There's a middle ground I aspire to. All I want from code is clarity. Not just for me, but for anyone who has to touch the code in the future. The first is so verbose in comments that you don't see the little code there is. And you couldn't see all the necessary code on the screen. The second (now) is so dense that you have to read the code carefully and slowly to understand what it's doing. I have the luxury of time when writing code, I can consider it and lay it out however I want, comment it how I want. To a person fighting a critical bug they lack this luxury. It's my job when I create code to help the person debugging it (even if it's me) to understand the code as quick as possible so that they may find and solve the problem as soon as possible. Three things I always remember when I code and design software: 1) Debugging is harder than writing code, so if you've been clever in writing code you are by definition not clever enough to debug it. 2) UNIX philosophy... do one thing well. 3) Write both the code and comments in a Hemingway style. Use no obscure language, keep it in layman's terms... but say only what you need to say.
- sbuk 15y ago
  Further to your 3rd point, you can go further and apply Orwell's 6 rules of writing from his essay "Politics and the English Language". The last rule is the most important. 1. Never use a metaphor, simile, or other figure of speech which you are used to seeing in print. 2. Never use a long word where a short one will do. 3. If it is possible to cut a word out, always cut it out. 4. Never use the passive where you can use the active. 5. Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent. 6. Break any of these rules sooner than say anything outright barbarous.
- hn_reader 15y ago
  > "To a person fighting a critical bug they lack this luxury. It's my job when I create code to help the person debugging it (even if it's me) to understand the code as quick as possible so that they may find and solve the problem as soon as possible." I am quite often in this situation - maintaining code written by others on a very tight schedule, weekends, evenings, trying to find and fix bugs and still make it to the next family commitment, etc. Wish more people understood this and considered the many future maintainers when writing their code.
citricsquid 15y ago
I find myself writing narratives, I think part of my own problem is the desire to justify and explain why I'm doing something the way I'm doing it, so at least if I ever have to come back and work with code I wrote a year earlier I'll know what the hell I was thinking when writing it.
- ajross 15y ago
  I still do that when I'm writing "hard" code. There, the process of exploring the problem space is happening as I'm typing the code, and putting it down in English helps me keep it all in my head while I translate it to code. But I find that once done, most of that stuff gets done it gets deleted or trimmed substantially. It tends to be embarassing to find it checked in later on.
phzbOx 15y ago
Still, the Emacslisp example would be easier to read/maintain/debug if it was separated in multiple functions.
Yrlec 15y ago
I think he should apply the same rules to his blog-posts. They always tend to be too verbose for my taste.
- Yrlec 15y ago
  Why the down-votes? Was it because you disagree or that you think that I offended someone? Sergey Brin seems to agree with me: http://techcrunch.com/2011/10/21/after-accidentally-public-rant-google-engineer-follows-up-with-a-homage-to-jeff-bezos/ http://techcrunch.com/2011/10/21/after-accidentally-public-r...
  - nyellin 15y ago
    You replied to an interesting and insightful article with irrelevant criticism of the author.
    - Yrlec 15y ago
      In what way was it irrelevant? I think he would have been able to get his point across a lot more efficiently if he had made it shorter. That also happened to be the point of his article (but in a different context).
ekidd 15y ago
Yegge says that novices don't like his second example. But I've been paid to maintain compilers written in Lisp, by people who've hacked in Lisp for decades, and I don't like it either: The "compressed" code example is not awful, but it's not a good example. An expert should make things clear, even if only to other experts. Basically, that function is too big, and it uses too many mutable variables. I had to stare at the control flow for 'destructuring' and 'init' for over a minute before I convinced myself that it actually worked correctly. More often than not, a deeply nested Lisp function with mutable variables will contain subtle bugs. So when I see something like this, I need to slow way down and take nothing on trust. Here are two ultra-compressed parsers that I like better than Yegge's: https://gist.github.com/1068185 https://gist.github.com/1068185 and http://book.realworldhaskell.org/read/using-parsec.html http://book.realworldhaskell.org/read/using-parsec.html To understand these, you'll need some specialized knowledge. But once you understand Yacc (or Parsec), this code is straightforward and clear. The structure of the code mimics the structure of the problem.
- ajross 15y ago
  OK, but you're criticizing his example from a functional perspective. You want to see something more scheme-like I guess (and frankly I'd agree). But that's not about metadata density, which is the point of his blog post.
  - prof_hobart 15y ago
    The two are related though - I very sparsely comment my code these days, but I cam do this partly because I break my code down into small self-describing functions with meaningful names.
- calebmpeterson 15y ago
  > Basically, that function is too big, and it uses too many mutable variables. An interesting statement that; particularly the part about mutable variables. Mutability implies state, and state seems to be something we, as programmers, often struggle with. Keeping the those state transitions within our mental model seems to be the hard part. I've been studying Clojure a lot over the past 12 months; it's approach is quite different from the 9-to-5 Java I write. Rich Hickey's notion of disentangling state into value and identity has been so very helpful to me in dealing with the 'problem' of mutability and state transitions in how I write my own code. Lisp, whatever the dialect, doesn't strike me as the sort of thing that most Java shops (particularly the large corporate variety) are going to swallow, but the ideas of Clojure... Perhaps I need to get out more, but it's the only language I've seen that proudly embraces a deeply functional paradigm without punting on State (or destroying my brain with monads). I have no deep love for Java, but once Java 8 arrives with lambdas, all I'll really want is a good implementation of persistent data structures. PS nothing against monads (or Haskell) - I just haven't gotten there in my Perlis journey.
bborud 15y ago
This seems a bit related to some discussions I've been having lately. Bear with me. Really good programmers act as multipliers of other people's productivity. If you can build on code that I write and my code makes you more productive, then that makes my work worth a lot more. If you have to work hard to understand my code, I have failed. But in order for that to happen, not only does my code have to be good enough or do something useful: you have to be able to understand how to make correct use of it. Which means that I have to be able to communicate this to you. This means that it is my job to express myself in a way that maximizes the probability that you will understand how to correctly leverage my code. This is an incredibly hard thing to do. So no, I don't think it is good enough to demand that other people wisen up and develop a tolerance for terseness. This is a somewhat self-centered attitude where the programmer sees himself or herself as the most important. Which is great if you want to do solo projects -- but not useful if you are to allow other programmers to use your talent as an amplifier for their own work and ideas. (Of course, I agree with Steve that comments that read like an entire narrative are excessive. But most programmers fail to document intent and non-obvious quirks. And also, adding vertical whitespace is useful to delineate "paragraphs" of code so one doesn't have to actually read the code, but one can scan the code vertically)
king_magic 15y ago
Well, I'm not going to completely dismiss him as a "cranky old dinosaur", but I don't agree with him, and frankly, I find it insulting that he issues a blanket declaration that those with 5-10 years experienced are "crazy teenagers", especially after showing pretty poorly written representative "good" code of his own. If I, a developer with 6 years experience, am a "crazy teenager", then he reminds me of a "senile old man". He has a few valid points, but overall, I think his message is unhelpful. I've written the occasional verbose comment before. Why? Well, for context: I was on a 20 person team, working on a poorly designed 750 KLOC codebase for a medical X-ray application. His example of incrementing a counter could have meant the difference between needing to re-shoot (and re-radiate a patient). When we made changes to critical pieces of the code (which were poorly designed before we ever touched it), we had to be exceedingly clear as to why. While my personal commenting style is more along the lines of his second code example, I see actual code in that function as pretty awful. It's long. It's confusing. The execution path through that code is not immediately clear. Sure, it's dense, but not in a good way. So, the while the author is free to rant, I think he should take a deep, hard look in the mirror before throwing out blanket criticisms of other developers the way he does.
- JoeAltmaier 15y ago
  English-language comments are usually full of prepositions, ambiguous terms and mostly stuff that was meaningful just to the author. Words about data in our out, upstream or downstream are always useless because nobody else has any idea what point of view you're taking (data produced BY your code, or produced FOR your code?) If you think you're making things clear to somebody coming after you, I'd guess you're wrong most of the time. And then, the code changes but the comment doesn't. Now its downright misleading. Also it's arrogant to imagine somebody who writes good code can also write good prose. Testing shows most folks are good at one or the other, right? Math or English, few can do both.
  - billswift 15y ago
    Unless they are an idiot savant, anyone who can do math very well can learn to use English (or whatever their native language is) competently. Anyone who says otherwise is making excuses, usually for laziness.
mark_l_watson 15y ago
I programmed in FORTRAN a lot in the 1970s and Lisp in the 1980s and I had the habit of starting to write new code by just writing entry points and then narrative comments like the ones in Steve's first example (but not so verbose). I would wait a while, do something else, then come back to my outline, and if the narrative outline still made sense, then I would add the code. (I was the only computer programmer in my large company with a private ocean view office, so the technique must have worked :-) I stopped using that coding technique eventually, and Steve's article gives me a good perspective of that transition.
mml 15y ago
You realize of course that the post isn't about code comments right?
- jodrellblank 15y ago
  If we don't, your comment doesn't help, and therefore is nothing more than boasting about how you "get it". So what is it about? Static typing? Acceptance of change in all things? Acceptance that code will always have flaws? Aging? Lisp code-is-data advocacy? How the difference between beginners and experienced people is as much slogging through grunt work as it is skill? How pragmatism wins over either strongly-for or strongly-against approaches? A reference to Joyce, as younger Steve Yegge "begins to question and rebel against the Java and Ruby conventions with which he has been raised."? What?
  - nyellin 15y ago
    The article is about being a pragmatic programmer. Know when to stop modeling, stop writing endless abstractions, and start writing code that does something. Don't model for the sake of modeling.
  - mml 15y ago
    You must be a gas at parties.
MatthewPhillips 15y ago
For me personally, stopping to comment on code breaks my concentration on coding. So I usually only do it after I've finished some task, and only at the function level. I don't see a point in explaining why I chose to use a while loop instead of a for loop. The next coder can change it if he/she dislikes the implementation. I would only have denser commenting on some code that I spent a lot of time optimizing for speed. I also have found in full-time and contracting work that your time estimates, or more precisely what the business/client desires your time to be, don't account for commenting, which for me personally can take quite a lot of time if done correctly. If done correctly a comment can convince me to change the code; if you can't easily explain what a function does then it might not need to exist.
staktrace 15y ago
I disagree with Steve's comparison of over-commenting with static typing. The key difference, I think, is that comments are purely for the human, whereas static typing also means something to the compiler. It allows the programmer to offload some work by letting the compiler check it, which comments do not do.
_m4 15y ago
I am a bit suprised to not see TDD or any of its siblings being pulled into the discussion. To me, the better someone is doing TD, the better the code communicates because TDD makes you think about the right things when coding. It sets your priorities straight. So the question of n00b or vet for me is just how well someone does TDD. And there is also this great book by Kent Beck about Implementation Patterns that is all about well-communication code.
raldi 15y ago
You can s/static typing/unit testing/g and still get a pretty good essay.
jebblue 15y ago
Any day of the week I'll take reading a comment for a few seconds to trying to get inside the mind of the original coder which can take minutes or hours or days.
losethos 15y ago
every noob is a guru on programming.
lyudmil 15y ago
Should a team write for the least common denominator? And if so, exactly how compressed should they make the code? I think the question may be unanswerable. I found this point quite interesting. It clearly matters whether the question has an answer and I suspect there's a way to determine that. If we buy into the whole "good programmers are 10x more productive than average programmers", then we can build a mathematical model of team productivity. We have X number of great programmers, Y number of average programmers, and Z number of bad programmers, each of whose productivities are mathematically (in this case, linearly) related. At this point the question becomes an operations research problem which ought to have a clear answer, which might be different depending on your team's configuration. (Question: Are there published, peer-reviewed papers measuring programmer productivity in this manner?) Suppose we don't believe we can actually reasonably compare one person's productivity to another. It then would seem reasonable to try to avoid the question altogether. The issue arises from different skill levels on a particular team, so if you could somehow guarantee people will have the same skill level (at least as it pertains to the specific project) then you no longer need to worry about how to write your code. I think this is what things like pair programming are trying to address - creating a team that is somehow aware of their average skill level and writes code in the appropriate style. This would also explain the general frustration people have with pair programming - if you haven't internalized the team's style, you're likely to either be either way over your head or having to slow yourself down and teach instead of getting as much done as possible.
TheEzEzz 15y ago
I would like to see a statically typed language with compile time checking of comments. If a comment references a function and the signature later changes, that comment should throw an error at compile time. It would also be nice if a comment, or parts of a comment, could be tethered to pieces of code, so that any modifications to that code will produce a warning indicating you should potentially update the comment.
jroseattle 15y ago
I had trouble getting to the conclusions that Steve has drawn here, mostly because I found the article all over the map. In the postscript, he talks about how difficult it was to write it and he actually cut stuff out. I think his intended message would be greatly improved with greater focus. I think he was attempting to draw from disparate things to build a picture of programmers at various stages of growth, but his conclusions read more like a list of general best practices. It was not what I expected as conclusions to the article.
dr_rezzy 15y ago
I didnt really pay much attention to the points regarding commenting style because it seemed like the real point here was the direction java was going in the late 2000's (or more importantly the ideas being sold). In this context, this posting comes together as very insightful and actually resonates with a lot of truth.
ecaradec 15y ago
I love the 2 years old Emily analogy.
jvoorhis 15y ago
RE: "Perl, Python and Ruby fail to attract many Java and C++ programmers because, well, they force you to get stuff done." As a seasoned Ruby programmer, I had the impression that Ruby with its metaprogramming api was just as much a metadata addict's paradise.
codeonfire 15y ago
All the very best and most experienced programmers (wink) will know ways to write code that both amateurs and elites can enjoy. I personally (wink) do things like extract expressions to give them meaningful identifiers, include units in parameter names, and sprinkle short one-liners throughout to summarize blocks of code.
jabkobob 15y ago
The problem with his 'noob' example is not only that the comments are overly verbose, but also that his variable names are generic and totally useless. 'counter' and 'pos' or 'ref' are so generic that you always have to look at the whole code before you know what's going on. Rename the 'counter' variable to 'bytesProcessed', and rename the 'pos' variable to 'startOfBuffer', and use a variable named 'currentByte' to walk through the buffer... With descriptive variable names many comments become unnecessary.
ww520 15y ago
The only rule I have for code style is to write it like a English paper, i.e. to make it easier to read and understand. Yes, I do put blank lines here to there, just to group things together.
omlette 15y ago
you can always hide/delete comments..

124 points by nyellin 15y ago

DanBC 15y ago

> If it's a complicated algorithm, a veteran programmer wants to see the whole thing on the screen, which means reducing the number of blank lines and inline comments – especially comments that simply reiterate what the code is doing. Don't text editors have, along with syntax highlighting, any "hide comments" and "compress whitespace especially blank lines" features?

__david__ 15y ago
Possibly, but those are actually kind of dangerous, because if you have the comments hidden and you are editing the code you probably aren't updating the comments. And stale comments are worse than no comments.
- ajross 15y ago
  Absolutely true. But your assumption that people being able to read comments means that they'll update them seems awfully naive. Comments become lies over time. They always do.
  - __david__ 15y ago
    I didn't mean to imply that and I completely agree with you. I'm not a huge commenter myself--my general rule is only comment what is weird or un-obvious and make the code readable with good function and variable names.

dirtyaura 15y ago

I like this one: "when in doubt, don't model it."

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.

rheide 15y ago

The narrative commenting style was particularly recognizable. I started out in Java ~8 years ago and only recently moved to Python. Whenever I used to write a particular algorithm in Java I would write comments in the narrative style described by the article. However, I noticed myself deleting large chunks of those comments as I revisited the code at a later point in time. Comment refactoring, so to speak. These days, in Python, I rarely write narratives, and when I do, I delete or shorten the narrative before I commit. Moral of the story: narratives can be useful to organize your brain, even with years of experience, but they should really be gone when the code (and your thought process) is finished.

deleted 15y ago

[deleted]

buro9 15y ago

Both fail for me. There's a middle ground I aspire to. All I want from code is clarity. Not just for me, but for anyone who has to touch the code in the future. The first is so verbose in comments that you don't see the little code there is. And you couldn't see all the necessary code on the screen. The second (now) is so dense that you have to read the code carefully and slowly to understand what it's doing. I have the luxury of time when writing code, I can consider it and lay it out however I want, comment it how I want. To a person fighting a critical bug they lack this luxury. It's my job when I create code to help the person debugging it (even if it's me) to understand the code as quick as possible so that they may find and solve the problem as soon as possible. Three things I always remember when I code and design software: 1) Debugging is harder than writing code, so if you've been clever in writing code you are by definition not clever enough to debug it. 2) UNIX philosophy... do one thing well. 3) Write both the code and comments in a Hemingway style. Use no obscure language, keep it in layman's terms... but say only what you need to say.

sbuk 15y ago
Further to your 3rd point, you can go further and apply Orwell's 6 rules of writing from his essay "Politics and the English Language". The last rule is the most important. 1. Never use a metaphor, simile, or other figure of speech which you are used to seeing in print. 2. Never use a long word where a short one will do. 3. If it is possible to cut a word out, always cut it out. 4. Never use the passive where you can use the active. 5. Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent. 6. Break any of these rules sooner than say anything outright barbarous.
hn_reader 15y ago
> "To a person fighting a critical bug they lack this luxury. It's my job when I create code to help the person debugging it (even if it's me) to understand the code as quick as possible so that they may find and solve the problem as soon as possible." I am quite often in this situation - maintaining code written by others on a very tight schedule, weekends, evenings, trying to find and fix bugs and still make it to the next family commitment, etc. Wish more people understood this and considered the many future maintainers when writing their code.

citricsquid 15y ago

I find myself writing narratives, I think part of my own problem is the desire to justify and explain why I'm doing something the way I'm doing it, so at least if I ever have to come back and work with code I wrote a year earlier I'll know what the hell I was thinking when writing it.

ajross 15y ago
I still do that when I'm writing "hard" code. There, the process of exploring the problem space is happening as I'm typing the code, and putting it down in English helps me keep it all in my head while I translate it to code. But I find that once done, most of that stuff gets done it gets deleted or trimmed substantially. It tends to be embarassing to find it checked in later on.

phzbOx 15y ago

Still, the Emacslisp example would be easier to read/maintain/debug if it was separated in multiple functions.

Yrlec 15y ago

I think he should apply the same rules to his blog-posts. They always tend to be too verbose for my taste.

Yrlec 15y ago
Why the down-votes? Was it because you disagree or that you think that I offended someone? Sergey Brin seems to agree with me: http://techcrunch.com/2011/10/21/after-accidentally-public-rant-google-engineer-follows-up-with-a-homage-to-jeff-bezos/ http://techcrunch.com/2011/10/21/after-accidentally-public-r...
- nyellin 15y ago
  You replied to an interesting and insightful article with irrelevant criticism of the author.
  - Yrlec 15y ago
    In what way was it irrelevant? I think he would have been able to get his point across a lot more efficiently if he had made it shorter. That also happened to be the point of his article (but in a different context).

ekidd 15y ago

Yegge says that novices don't like his second example. But I've been paid to maintain compilers written in Lisp, by people who've hacked in Lisp for decades, and I don't like it either: The "compressed" code example is not awful, but it's not a good example. An expert should make things clear, even if only to other experts. Basically, that function is too big, and it uses too many mutable variables. I had to stare at the control flow for 'destructuring' and 'init' for over a minute before I convinced myself that it actually worked correctly. More often than not, a deeply nested Lisp function with mutable variables will contain subtle bugs. So when I see something like this, I need to slow way down and take nothing on trust. Here are two ultra-compressed parsers that I like better than Yegge's: https://gist.github.com/1068185 https://gist.github.com/1068185 and http://book.realworldhaskell.org/read/using-parsec.html http://book.realworldhaskell.org/read/using-parsec.html To understand these, you'll need some specialized knowledge. But once you understand Yacc (or Parsec), this code is straightforward and clear. The structure of the code mimics the structure of the problem.

ajross 15y ago
OK, but you're criticizing his example from a functional perspective. You want to see something more scheme-like I guess (and frankly I'd agree). But that's not about metadata density, which is the point of his blog post.
- prof_hobart 15y ago
  The two are related though - I very sparsely comment my code these days, but I cam do this partly because I break my code down into small self-describing functions with meaningful names.
calebmpeterson 15y ago
> Basically, that function is too big, and it uses too many mutable variables. An interesting statement that; particularly the part about mutable variables. Mutability implies state, and state seems to be something we, as programmers, often struggle with. Keeping the those state transitions within our mental model seems to be the hard part. I've been studying Clojure a lot over the past 12 months; it's approach is quite different from the 9-to-5 Java I write. Rich Hickey's notion of disentangling state into value and identity has been so very helpful to me in dealing with the 'problem' of mutability and state transitions in how I write my own code. Lisp, whatever the dialect, doesn't strike me as the sort of thing that most Java shops (particularly the large corporate variety) are going to swallow, but the ideas of Clojure... Perhaps I need to get out more, but it's the only language I've seen that proudly embraces a deeply functional paradigm without punting on State (or destroying my brain with monads). I have no deep love for Java, but once Java 8 arrives with lambdas, all I'll really want is a good implementation of persistent data structures. PS nothing against monads (or Haskell) - I just haven't gotten there in my Perlis journey.

bborud 15y ago

This seems a bit related to some discussions I've been having lately. Bear with me. Really good programmers act as multipliers of other people's productivity. If you can build on code that I write and my code makes you more productive, then that makes my work worth a lot more. If you have to work hard to understand my code, I have failed. But in order for that to happen, not only does my code have to be good enough or do something useful: you have to be able to understand how to make correct use of it. Which means that I have to be able to communicate this to you. This means that it is my job to express myself in a way that maximizes the probability that you will understand how to correctly leverage my code. This is an incredibly hard thing to do. So no, I don't think it is good enough to demand that other people wisen up and develop a tolerance for terseness. This is a somewhat self-centered attitude where the programmer sees himself or herself as the most important. Which is great if you want to do solo projects -- but not useful if you are to allow other programmers to use your talent as an amplifier for their own work and ideas. (Of course, I agree with Steve that comments that read like an entire narrative are excessive. But most programmers fail to document intent and non-obvious quirks. And also, adding vertical whitespace is useful to delineate "paragraphs" of code so one doesn't have to actually read the code, but one can scan the code vertically)

king_magic 15y ago

Well, I'm not going to completely dismiss him as a "cranky old dinosaur", but I don't agree with him, and frankly, I find it insulting that he issues a blanket declaration that those with 5-10 years experienced are "crazy teenagers", especially after showing pretty poorly written representative "good" code of his own. If I, a developer with 6 years experience, am a "crazy teenager", then he reminds me of a "senile old man". He has a few valid points, but overall, I think his message is unhelpful. I've written the occasional verbose comment before. Why? Well, for context: I was on a 20 person team, working on a poorly designed 750 KLOC codebase for a medical X-ray application. His example of incrementing a counter could have meant the difference between needing to re-shoot (and re-radiate a patient). When we made changes to critical pieces of the code (which were poorly designed before we ever touched it), we had to be exceedingly clear as to why. While my personal commenting style is more along the lines of his second code example, I see actual code in that function as pretty awful. It's long. It's confusing. The execution path through that code is not immediately clear. Sure, it's dense, but not in a good way. So, the while the author is free to rant, I think he should take a deep, hard look in the mirror before throwing out blanket criticisms of other developers the way he does.

JoeAltmaier 15y ago
English-language comments are usually full of prepositions, ambiguous terms and mostly stuff that was meaningful just to the author. Words about data in our out, upstream or downstream are always useless because nobody else has any idea what point of view you're taking (data produced BY your code, or produced FOR your code?) If you think you're making things clear to somebody coming after you, I'd guess you're wrong most of the time. And then, the code changes but the comment doesn't. Now its downright misleading. Also it's arrogant to imagine somebody who writes good code can also write good prose. Testing shows most folks are good at one or the other, right? Math or English, few can do both.
- billswift 15y ago
  Unless they are an idiot savant, anyone who can do math very well can learn to use English (or whatever their native language is) competently. Anyone who says otherwise is making excuses, usually for laziness.

mark_l_watson 15y ago

I programmed in FORTRAN a lot in the 1970s and Lisp in the 1980s and I had the habit of starting to write new code by just writing entry points and then narrative comments like the ones in Steve's first example (but not so verbose). I would wait a while, do something else, then come back to my outline, and if the narrative outline still made sense, then I would add the code. (I was the only computer programmer in my large company with a private ocean view office, so the technique must have worked :-) I stopped using that coding technique eventually, and Steve's article gives me a good perspective of that transition.

mml 15y ago

You realize of course that the post isn't about code comments right?

jodrellblank 15y ago
If we don't, your comment doesn't help, and therefore is nothing more than boasting about how you "get it". So what is it about? Static typing? Acceptance of change in all things? Acceptance that code will always have flaws? Aging? Lisp code-is-data advocacy? How the difference between beginners and experienced people is as much slogging through grunt work as it is skill? How pragmatism wins over either strongly-for or strongly-against approaches? A reference to Joyce, as younger Steve Yegge "begins to question and rebel against the Java and Ruby conventions with which he has been raised."? What?
- nyellin 15y ago
  The article is about being a pragmatic programmer. Know when to stop modeling, stop writing endless abstractions, and start writing code that does something. Don't model for the sake of modeling.
- mml 15y ago
  You must be a gas at parties.

MatthewPhillips 15y ago

For me personally, stopping to comment on code breaks my concentration on coding. So I usually only do it after I've finished some task, and only at the function level. I don't see a point in explaining why I chose to use a while loop instead of a for loop. The next coder can change it if he/she dislikes the implementation. I would only have denser commenting on some code that I spent a lot of time optimizing for speed. I also have found in full-time and contracting work that your time estimates, or more precisely what the business/client desires your time to be, don't account for commenting, which for me personally can take quite a lot of time if done correctly. If done correctly a comment can convince me to change the code; if you can't easily explain what a function does then it might not need to exist.

staktrace 15y ago

I disagree with Steve's comparison of over-commenting with static typing. The key difference, I think, is that comments are purely for the human, whereas static typing also means something to the compiler. It allows the programmer to offload some work by letting the compiler check it, which comments do not do.

_m4 15y ago

I am a bit suprised to not see TDD or any of its siblings being pulled into the discussion. To me, the better someone is doing TD, the better the code communicates because TDD makes you think about the right things when coding. It sets your priorities straight. So the question of n00b or vet for me is just how well someone does TDD. And there is also this great book by Kent Beck about Implementation Patterns that is all about well-communication code.

raldi 15y ago

You can s/static typing/unit testing/g and still get a pretty good essay.

jebblue 15y ago

Any day of the week I'll take reading a comment for a few seconds to trying to get inside the mind of the original coder which can take minutes or hours or days.

losethos 15y ago

every noob is a guru on programming.

lyudmil 15y ago

Should a team write for the least common denominator? And if so, exactly how compressed should they make the code? I think the question may be unanswerable. I found this point quite interesting. It clearly matters whether the question has an answer and I suspect there's a way to determine that. If we buy into the whole "good programmers are 10x more productive than average programmers", then we can build a mathematical model of team productivity. We have X number of great programmers, Y number of average programmers, and Z number of bad programmers, each of whose productivities are mathematically (in this case, linearly) related. At this point the question becomes an operations research problem which ought to have a clear answer, which might be different depending on your team's configuration. (Question: Are there published, peer-reviewed papers measuring programmer productivity in this manner?) Suppose we don't believe we can actually reasonably compare one person's productivity to another. It then would seem reasonable to try to avoid the question altogether. The issue arises from different skill levels on a particular team, so if you could somehow guarantee people will have the same skill level (at least as it pertains to the specific project) then you no longer need to worry about how to write your code. I think this is what things like pair programming are trying to address - creating a team that is somehow aware of their average skill level and writes code in the appropriate style. This would also explain the general frustration people have with pair programming - if you haven't internalized the team's style, you're likely to either be either way over your head or having to slow yourself down and teach instead of getting as much done as possible.

TheEzEzz 15y ago

I would like to see a statically typed language with compile time checking of comments. If a comment references a function and the signature later changes, that comment should throw an error at compile time. It would also be nice if a comment, or parts of a comment, could be tethered to pieces of code, so that any modifications to that code will produce a warning indicating you should potentially update the comment.

jroseattle 15y ago

I had trouble getting to the conclusions that Steve has drawn here, mostly because I found the article all over the map. In the postscript, he talks about how difficult it was to write it and he actually cut stuff out. I think his intended message would be greatly improved with greater focus. I think he was attempting to draw from disparate things to build a picture of programmers at various stages of growth, but his conclusions read more like a list of general best practices. It was not what I expected as conclusions to the article.

dr_rezzy 15y ago

I didnt really pay much attention to the points regarding commenting style because it seemed like the real point here was the direction java was going in the late 2000's (or more importantly the ideas being sold). In this context, this posting comes together as very insightful and actually resonates with a lot of truth.

ecaradec 15y ago

I love the 2 years old Emily analogy.

jvoorhis 15y ago

RE: "Perl, Python and Ruby fail to attract many Java and C++ programmers because, well, they force you to get stuff done." As a seasoned Ruby programmer, I had the impression that Ruby with its metaprogramming api was just as much a metadata addict's paradise.

codeonfire 15y ago

All the very best and most experienced programmers (wink) will know ways to write code that both amateurs and elites can enjoy. I personally (wink) do things like extract expressions to give them meaningful identifiers, include units in parameter names, and sprinkle short one-liners throughout to summarize blocks of code.

jabkobob 15y ago

The problem with his 'noob' example is not only that the comments are overly verbose, but also that his variable names are generic and totally useless. 'counter' and 'pos' or 'ref' are so generic that you always have to look at the whole code before you know what's going on. Rename the 'counter' variable to 'bytesProcessed', and rename the 'pos' variable to 'startOfBuffer', and use a variable named 'currentByte' to walk through the buffer... With descriptive variable names many comments become unnecessary.

ww520 15y ago

The only rule I have for code style is to write it like a English paper, i.e. to make it easier to read and understand. Yes, I do put blank lines here to there, just to group things together.

omlette 15y ago

you can always hide/delete comments..