Portrait of a Noob

I read this a while back and i still remember the takeaway point from it :<p>"It's denser: there's less whitespace and far less commenting. Most of the commenting is in the form of doc-comments for automated API-doc extraction"<p>This is right on the button. I prefer writing/reading an overall README.txt which says concisely what that module/package etc. is supposed to do and doc-comments where appropriate when something is not obvious. Anything else and i automatically start seeing that as noise filtering it as i go along. The worst are the obvious and/or the outdated ones.

He's spot-on about Java being a safe-haven for "data modeling" geeks who are afraid of doing real work. Writing a whole bunch of getters and setters in a freshly minted Java class certainly feels like work. However, I think he gets it wrong when he puts OCaml on the extreme "for you to model everything" end of the spectrum:<p><i>And Haskell, OCaml and their ilk are part of a 45-year-old static-typing movement within academia to try to force people to model everything. Programmers hate that. These languages will never, ever enjoy any substantial commercial success</i><p>Hold on a minute...last time I checked OCaml was a dialect of ML. ML does not ask you to "statically" type everything, in fact it does the opposite. It infers all the types. Sure, it allows you to hint types to the compiler, but this is not necessary. You get all the benefits of "static" type checking through ML's concept of type inference. It's designed specifically to make it less work for the programmer to enjoy the benefits of a sound, correct type system.<p>If you want to learn more about type inference in ML, check out this short introduction: <a href="http://bit.ly/8WEhD8" rel="nofollow">http://bit.ly/8WEhD8</a>

Comments are invisible until the moment you need them.<p>When you understand your code, you don't bother to read the comments. As soon as you forget how the code works, you look to the comments for direction.<p>But if you didn't revise your comments along with your code, the comments will trick and deceive you until you realize that they're out of date. So you must re-grok the code anyway.<p>Use comments to describe your code's <i>purpose</i>. Let your code self-document the implementation.If you are particularly clever in your implementation, add a quick comment to explain your cleverness. When you realize you shouldn't have been so clever, be sure to remove the implementation comment as well.

I've shared Yegge's disdain for static typing for quite some time. One of the best examples of how awful it can be is type hinting (optional type constraints on parameters) in PHP. Many times I've explained to people why type hints are awful thing deserving banishment to hell — along with Facebook suggestions and Microsoft product recommendations — but so many PHP programmers seem to love them! Now that I read this I can see why that sort of thinking is bound to exist for a language like PHP (read: noobs).<p>Recently, however, I've been getting into Haskell and in doing so I found my opinion on static typing left a little beaten in the legs and suffering some obvious facial wounds. Static typing works in Haskell, I'm pretty sure of that. The question I'm left with is, why?<p>I think it might have something to do with the fact that type checks in class-based OO languages don't even begin to insure the program correctness that novices are often foolish enough to think they do. Everyone else recognizes the need for all manner of testing, and that's how correctness is proved (albeit, approximately) in imperative languages. In Haskell, I've found that type checks go quite some way to proving correctness, no really! (They don't actually prove correctness but proofs of correctness would be impossible without them). Without even bothering to do any proofs or testing you get a much more rigorous check for correctness in Haskell than you do when a Java program successfully compiles.<p>I can't emphasize this difference enough. To me static typing in Java is an annoyance and a lie. And so when I program in a language that teeters between static and dynamic typing, such as PHP, I go out of my way to write libraries that make things more dynamic (I've got one GitHub) and I call men who advocate aforementioned type hinting, girls names. In Haskell, it's totally different; it actually works; it's actually useful. Not to mention the clever stuff that you can do with types which I couldn't begin to do justice here given my inexperience.

I'm suprised no one mentions this, good code does not need comments, because it clearly speaks with variable names and function names.<p>The Lisp function Yegge gives, is horrible in that aspect. for example this piece of code:<p><pre><code> (if (or (= tt js2-LB) (= tt js2-LC))</code></pre> should really be more like<p><pre><code> (if (matches-js2-line-ending current_token)) </code></pre> No matter "how good you are" code reading is faster if what you read matches with what you're doing in English.

Yet again, the title of reposts needs to be dated. I was bittersweet hopeful this was one of the final 3 posts he has promised us since May.

I'm not a big fan of lots of comments in the code itself, but I very much so advocate design documentation.<p>I once had the pleasure of rewriting an Ada avionics subsystem in C. The code was very tersely commented, and the only documentation I could find on the subsystem was a requirement to the effect of "such-and-such subsystem shall exist". So I was left to figuring out what the subsystem worked from the code itself.<p>That's possible to do, but things would have gone a lot faster if I would have had a few pages describing what the goals and overall architecture of the software was.

Old HN thread about this essay: <a href="http://news.ycombinator.com/item?id=113244" rel="nofollow">http://news.ycombinator.com/item?id=113244</a>

From the article:<p><i>If you're a n00b, you'll look at experienced code and say it's impenetrable, undisciplined crap written by someone who never learned the essentials of modern software engineering. If you're a veteran, you'll look at n00b code and say it's over-commented, ornamental fluff that an intern could have written in a single night of heavy drinking.</i><p>I have never seen this so succinctly expressed before.

This completely does not match my experience. When I first started programming, and even after a year or two in the industry, I used to write zero comments. Or maybe a line or two of comments every few thousands lines of code. Then, I started adding comments in places I thought required explanation and above function declarations. After I joined Google I was taught by smart people to add a comment every ten lines of code or so explaining what the next ten lines of code do.<p>I still don't write much comments when doing hobby programming at home (after all, the whole point of hobby is to indulge yourself), but there is no slightest doubt in my mind that abundance of comments is a good thing. I've never really seen code I considered overcommented. I see code which is severely undercommented all the time.

The first part seems to be motivating something like a macro system for comments. What if one abbreviated compound situations using a single word or a phrase along with a separate file with expansions of the abbreviations into more detail. So, one can comment at a more abstract level and still be understandable (using say, a tool which displays the expansion when hovering over the abbreviation, or a separate window with expansions of all the abbrevs used nearby). Ideally, of course, the abstraction would be captured in the code itself, and the expansion would be the comment before the function or the macro defining the abstraction. So this system will be useful only when there are abstractions in comments which are not reflected in the code.

This is one of the most inspired pieces of writing on programming I've read in quite some time. Acknowledging the difference in preference for code density among noobs vs. seasoned programmers will be really useful during any annoying meetings on programming style I have to attend in the future.<p>Edit: It got less inspired as I continued to read but the initial idea was good.

If it was poorly written code, I'd rather see those huge comments just so I knew what was going through the authors head. I think if it's poorly written code with "no" comments, then you have even bigger problems.<p>I want to say I read that entire article, but I only read the first few paragraphs, so, my comment may be off topic somehow. That was a hefty post!

For a second I thought maybe Steve had made a new blog entry :(

That's a very large function for an experienced programmer. In my opinion, each function should do one thing and that thing should be the name of the function.

This is one of Yegge's most stupid rants. I strongly recommend SQLite Dr. Hipp's video presentations on how to write well commented code.

Loved it and found myself nodding along.<p>Anyone else catch the irony that this essay was really long?

I refute Yegge thusly: Which code would you rather maintain?