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

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.

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?

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

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.

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

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.

In a large code base, I doubt you'll be able to get a "big picture" view from any one file.

I also think that some of those functions are too large even without their comments, exec_simple_query is gigantic.

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

I doubt Yegge argues against well written comments.

(Personally, I wonder if I should start to sign everything I write with "/eternal teenager"? :-( :-) )

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 :-) )

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.

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.

Citation needed. And I don't mean proof by appeal to authority because someone famous once said it.

Debugging is different to writing code - you can spend longer thinking about it, you can bring different tools to bear on it, you can focus your attention on smaller or larger pieces of the problem, you can stop thinking about any of the surrounding context which is irrelevant to debugging, instead of having to think about the context relevant for programming.

Is it measurably harder, or is it a less used and less practised skill so not learned as fluently? Is it that programming is seen as "default-success-unless-proved-broken" and debugging is seen as "a-failure-until-fixed", so there's a psychologically different feeling in approaching one than the other? Is it that programming usually happens earlier in a project and debugging later, so there's more stress and deadlines looming? Is it that debugging happens when a problem has been found and now you are acutely aware of what's being held up until the debugging is done?

This quote suggests there is code out there which has known bugs and the authors have tried hard to find them, with enough examples to work from, and never succeeded due specifically to limits of their cleverness. Is this anecdotally true for anyone here?

If you're debugging your own code, you're trying to find something out about it that you didn't understand when you wrote it. You're looking for one of an almost infinite variety of side effects or subtle misunderstandings of interfaces, and you have to find which one it is. There are usually more ways to go wrong than right. You then have to change your brain to add this understanding, which is difficult, while writing code is likely to take advantage of existing mental structures.

When you're debugging someone else's code, you have all the same problems, except you don't have the benefit of knowing what the writer was thinking at the time, that initial understanding.

So yes, you have more time to do it, but that's because it takes longer, and it's more a wrack-your-brains time than writing code.

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.

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.

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.

Sorry, that's just a failure of the programmer, same as any other coding mistake they may make. It is by no means a reason to not have comments.

Having essentially the same code written in two places (code and comment) absolutely BEGS for them to get out of sync. Its why we write modules, subroutines etc - get it right once.

Comments are evil if they mention the code. They should be about constraints, the compiler, your wife, ANYTHING but the code.

This isn't double documentation -- it's complementary documentation. Code is the what, comments are the why. If one does not match the other, then again, that's on the programmer.

        //how many frames should have been received since the last

        // update if too many have been dropped or there have been

        // big delays won't allow this reduction may no longer need

        // the send_ts_diff here

        num_pkts_expected = (int)(((float)(arr_ts -

                                           bwest_str->last_update_ts) * 1000.0f /(float) FS) /

                                  (float)frame_length);

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)

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.

Don't text editors have, along with syntax highlighting, any "hide comments" and "compress whitespace especially blank lines" features?

As a seasoned Ruby programmer, I had the impression that Ruby with its metaprogramming api was just as much a metadata addict's paradise.

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.

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.

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?

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.

I stopped using that coding technique eventually, and Steve's article gives me a good perspective of that transition.