Stevey “Long Long” Yegge strikes again.
And this time it cuts twice: first it wasted a lot of my time as usual, then it showed why I suck at being a developer: I can’t get over the n00b mentality and capacity.
OK it’s not that bad. I’ll never be able to write a compiler or understand LISP, but I don’t think my code has that much of a chance to be honored on the Daily WTF, either.
This is the paragraph that makes me sweat (bold by me):
A programmer with a high tolerance for compression is actually hindered by a screenful of storytelling (referring to long comments). Why? Because in order to understand a code base you need to be able to pack as much of it as possible into your head. 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. This is exactly the opposite of what a n00b programmer wants. n00bs want to focus on one statement or expression at a time, moving all the code around it out of view so they can concentrate, fer cryin’ out loud.
I would always cringe at the LISP code segment he quoted, not just because it’s LISP, but mostly because it’s too terse and dense, exactly as he wants it. My current team lead writes code just like that, and now I can understand his smirk whenever I ask him for more comments.
Stevey’s take home messages are clear, balanced, and easy to follow, though. The essence is the same as the original Agile Manifesto, which is working code (including test code) is the one and only true goal of development. Not any kind of artifact (Stevey calls it metadata) like process, model, and documentation.
When in doubt, don’t model it. Just get the code written, make forward progress. Don’t let yourself get bogged down with the details of modeling a helper class that you’re creating for documentation purposes.
If it’s a public-facing API, take a lesson from doc-comments (which should be present even in seasoned code), and do model it. Just don’t go overboard with it. Your users don’t want to see page after page of diagrams just to make a call to your service.
Lastly, if you’re revisiting your code down the road and you find a spot that’s always confusing you, or isn’t performing well, consider adding some extra static types to clarify it (for you and for your compiler). Just keep in mind that it’s a trade-off: you’re introducing clarifying metadata at the cost of maintenance, upkeep, flexibility, testability and extensibility. Don’t go too wild with it.