Judging by his blog posts, can you imagine how much commenting he did as a n00b? Something tells me those examples at the top of his post weren't that far off.
He never said that prose should be terse. In fact, he is on record as saying that in order for writing, it has to be long enough to force the reader to remember it. If you're not willing to take ~15-20 min to read his essays, are you really going to internalize his recommendations?
Noob here (4 yrs). Muddled code is perfectly ok so long as you wall it off, jesus H christ. The UI should be separate from the machinery, seperate from the data it works on & outputs. Add a bit of refactoring & I'll be perfectly happy, I promise.
Some people, noob or not, have a style. Some code has a style. Some programs are best expressed as narrative little stories and documenting them as such makes sense. This is often true when the program's data flow is very linear.
Some programs benefit greatly by having dense little blocks, with nothing more than a two work reminder as to what they do, that can be considered carefully and held tightly in the mind. Any program that has atomic/blocking operations or concurrency seems to fit this model.
To say that "noobs use a lot of this kind of comment" and "mature programmers use this different style" may be partly true but seems very much overly simplistic.
One problem that Steve doesn't talk about is that books on programming and all kinds of tutorials are mostly written by noobs and teenagers, and for a reason that's I think intuitively clear, vets rarely write tutorials. This is a pain for the industry as actually propaganda of bad or wrong styles of programming propagates itself through these kind of noob/teenage books. With very few exceptions.
Before he branched off to the static type discussion, I thought he was going to propose a code editor which facilitated meta-data comments. That way the programmer could provide comments as verbose as he liked and the reader could decide whether to view them. They could include links, additional documentation, etc. The code and comments could be viewed in a split-screen, separate windows, etc. Maybe this exists?
As far as I've been able to find, there isn't. And yes, I think there would be value in something like this. I'm actually working on a weird doxygen/wiki/interaction-graph hybrid thing to ease code comprehension at the moment. Not far along though, so I'm not sure it'll be as useful as I'm hoping it will be.
You can collapse/expand comment blocks in Visual Studio, although I'm not sure if VS can hide all of them at once. If not, it's a matter of writing a very simple plug-in. But anyway, that's not my point.
I think the idea of turning your plain-text source code into a 3D monster that requires a special rendering engine - is a wrong idea if you are in the webapp business. My server was under a massive attack recently and what saved my arse was terse and beautiful server-side code that I changed with vi on the fly. But of course we all know it's not only about attacks. Thus, unless we have magical IDEs that can edit and compile projects remotely on a Mars Rover, the conservative mantra Source code must be plain text wins.
So there's no hope for noobs. Either you jump onto the veterans' boat straight away or you don't even start programming. Ok, just kidding.
Damn Steve Yegge, my comments become longer than usual after reading his posts.
The source code could remain plain text. For those who want to view the meta-comments, their meta-comment-enabled IDE would open the plain text with its accompanying meta-comment file.
The problem with the now-you-see-it-now-you-don't approach is that, when you separate the code and the comments, they quickly diverge. The veteran will tinker with the code but never touch the comments, because she doesn't see them and doesn't care to see them. Then the comments become worse than useless, because they will actively mislead or confuse the newb who reads and writes them.
This is a special case of the general problem with metadata: you can't keep it in sync with the real data. This is what leads, e.g., Ruby programmers to become religious fanatics about DRY.
The other problem is that not all comments are equal: some are fluff, some are fluffy-looking but destined to become HTML documentation and are therefore important to keep around, some are terse and vital, some are hints for future refactorings and bug fixes. A system which hides all comments isn't really what I would want; I'd want to hide the fluffy ones and keep the important ones visible. And suddenly you need meta-metadata, and your editor becomes baroque, and your head explodes.
If the meta-comment system was useful enough, it might not be neglected. The meta-metadata is what could add a lot of value. You could tag your comments and make them selectively visible when they are relevant to the task at hand.
As well, I think the article could have been compressed significantly; it's overly wordy. Mr. Yegge should apply his programming manifesto to his writing.
Some of us read for fun, and his writing is fun! What you describe as "irrelevant" others of us see as "exposition." He follows a fairly well established tradition of using stuff unrelated to programming to illustrate programming (see Joel Spolsky and Philip Greenspun for more irrelevancies).
I'm curious to hear replies from people experienced with Scala, Haskell, or other static-functional languages.
I've looked at Scala, and type inference seems like it would be a big win compared to declare-every-type languages like Java. (I haven't written Scala programs so I don't know for sure.) I haven't learned Haskell, but I get turned off by the school-marm "statefulness is sin" attitude. I like that Lisps generally push you in the direction of good functional programming style without preventing you from doing imperative, or OO, or whatever style you think matches your particular problem best.
However, what the static-functional languages seem to have going for them is giving the compiler more to work with to improve performance. Scala and Haskell seem to do well on benchmark tasks. And, despite being turned off by Haskell's draconian enforcement of pure-functional programming, I was impressed when I saw that you could enable parallelization with a simple annotation on the section of code you wanted to run concurrently. Of course, Erlang fits this as well, but I think is not nearly as fast as Haskell for sequential code perhaps due to lack of static typing.
I admire SBCL for the performance they get out of Common Lisp. I've heard they do good type inferencing even on dynamically typed code, and of course Common Lisp has optional type declarations that the compiler can use to speed things up.
So, it appears that strong static typing might enable compilers that emit faster code. What do you all think?
Do most programmers really go through a "MUST COMMENT EVERYTHING" phase? I never did. If anything, I probably commented too LITTLE as opposed to too MUCH. In fact, I rarely comment more than the beginnings of new functions/methods/def*s.
Maybe I'm not doing anything sufficiently tricky in my functions?
I've yet to meet a "junior" programmer that overly comments code. OTOH I've met a couple of more senior level developers (15-20 years of experience) that absolutely can't live without documentation and comments even when the comments simply reiterate what the code is saying (still not to the level of narrative Steve was suggesting)
I began over-commenting in college when the professors asked for detailed comments but didn't exactly specify how much detail was enough. (Or, they tried to explain what comments were appropriate but failed miserably). Grade-wise, it was safer to have too many than too few.
Comments, like anything to do with writing maintainable code, take a while to learn. You only really figure out which comments are useful when you come back to something you wrote a couple of years ago, and try to make sense of it.
So, new programmers are likely to write bad comments, more than they are likely to write bad code (because bad code is more obvious the day you write it, so the feedback comes faster).
How the comments are bad, though, is going to vary between programmers. Some will write too many, some too few, some will just write plain useless comments.
My disease was like Steve's - over-commenting. I put it down to my liberal-arts background, which meant I found it much easier to think in prose than in code. Accordingly, I would get my head round tricky problems by writing a comment about them first. I wonder if programmers from a straight CS background would tend to write fewer comments.
30 comments
[ 0.15 ms ] story [ 75.7 ms ] threadquite funny
Some programs benefit greatly by having dense little blocks, with nothing more than a two work reminder as to what they do, that can be considered carefully and held tightly in the mind. Any program that has atomic/blocking operations or concurrency seems to fit this model.
To say that "noobs use a lot of this kind of comment" and "mature programmers use this different style" may be partly true but seems very much overly simplistic.
this is sorta inconsistent! i am confused
*http://www.sdtimes.com/article/column-20071015-01.html
I think the idea of turning your plain-text source code into a 3D monster that requires a special rendering engine - is a wrong idea if you are in the webapp business. My server was under a massive attack recently and what saved my arse was terse and beautiful server-side code that I changed with vi on the fly. But of course we all know it's not only about attacks. Thus, unless we have magical IDEs that can edit and compile projects remotely on a Mars Rover, the conservative mantra Source code must be plain text wins.
So there's no hope for noobs. Either you jump onto the veterans' boat straight away or you don't even start programming. Ok, just kidding.
Damn Steve Yegge, my comments become longer than usual after reading his posts.
This is a special case of the general problem with metadata: you can't keep it in sync with the real data. This is what leads, e.g., Ruby programmers to become religious fanatics about DRY.
The other problem is that not all comments are equal: some are fluff, some are fluffy-looking but destined to become HTML documentation and are therefore important to keep around, some are terse and vital, some are hints for future refactorings and bug fixes. A system which hides all comments isn't really what I would want; I'd want to hide the fluffy ones and keep the important ones visible. And suddenly you need meta-metadata, and your editor becomes baroque, and your head explodes.
I've looked at Scala, and type inference seems like it would be a big win compared to declare-every-type languages like Java. (I haven't written Scala programs so I don't know for sure.) I haven't learned Haskell, but I get turned off by the school-marm "statefulness is sin" attitude. I like that Lisps generally push you in the direction of good functional programming style without preventing you from doing imperative, or OO, or whatever style you think matches your particular problem best.
However, what the static-functional languages seem to have going for them is giving the compiler more to work with to improve performance. Scala and Haskell seem to do well on benchmark tasks. And, despite being turned off by Haskell's draconian enforcement of pure-functional programming, I was impressed when I saw that you could enable parallelization with a simple annotation on the section of code you wanted to run concurrently. Of course, Erlang fits this as well, but I think is not nearly as fast as Haskell for sequential code perhaps due to lack of static typing.
I admire SBCL for the performance they get out of Common Lisp. I've heard they do good type inferencing even on dynamically typed code, and of course Common Lisp has optional type declarations that the compiler can use to speed things up.
So, it appears that strong static typing might enable compilers that emit faster code. What do you all think?
Maybe I'm not doing anything sufficiently tricky in my functions?
So, new programmers are likely to write bad comments, more than they are likely to write bad code (because bad code is more obvious the day you write it, so the feedback comes faster).
How the comments are bad, though, is going to vary between programmers. Some will write too many, some too few, some will just write plain useless comments.
My disease was like Steve's - over-commenting. I put it down to my liberal-arts background, which meant I found it much easier to think in prose than in code. Accordingly, I would get my head round tricky problems by writing a comment about them first. I wonder if programmers from a straight CS background would tend to write fewer comments.