Where’s Lou

Had a great time at the minnebar (un)conference yesterday. Many of the sessions were very interesting and I saw a lot of familiar faces. The highlight for me however was the chance to hear the creator of RoR being interviewed. He’s the one the left, David Heinemeier Hansson, being interviewed by Jamie Thingelstad.

The guy was amazing. I agreed with everything he said.

I especially loved was how he didn’t have that “stick it to the man” vibe when he spoke about open source. In my opinion no matter how you feel about Microsoft the casual computing and on-line markets wouldn’t exist in the way they do today without them. Instead he seemed to have a completely pragmatic attitude of “getting shit done” in a programmer oriented way. Know what I mean? It’s not about disliking Sun, just that Java wasn’t helping him in the ways he wanted it to. Another example of this is when David stated he had originally tried to build out php on rails but the language seemed to reject it. Php, like Ruby, is also a free language so it isn’t so much “Ruby because it’s free” as “Ruby was right for the job”.

Another of his beliefs that struck me was about the beauty and aesthetics of code, and how documentation of code is a crutch. For example if you or someone else can’t return to your code and simply understand what it does by reading it then there’s something wrong. But the thing that’s wrong isn’t a lack of comments and documentation - it’s that the code wasn’t written simply or elegantly enough. I love that! I’ve always said based on the 90/10 or 80/20 rule - the majority of compute resources are spent running a minority of the volume of the code - only 10 or 20% of the code will be called often enough to make it even worth optimizing. The remaining 80 to 90% of the code in your project should be written for simplicity and clarity - nothing more and nothing less.

I could be wrong of course. If I was a journalist I would “do research” and “read things” on “the internet” before I wrote this. But hey, it’s my blog and that’s the impression I got. What more can I do? Other than the things I mentioned three sentences ago. But it’s getting late. Let’s call that an exercise for the reader.

He also had some really interesting things to say when he was asked about enterprise software! He said enterprise software does benefit some people, specifically the vendors and decision makers who buy and sell enterprise software because there’s lots of travel, expense accounts, and steak dinners. But in the end it does nothing for the poor programmer who has to figure out how to apply the garbage to a real world problem. I know I’ve seen some cases as a consultant where the wrong tools have been used as part of a client mandate pretty much only to justify an earlier purchasing decision. So I had a laugh about that one.

In my professional life I still believe it would be counterproductive for our department to switch to RoR, since our entire technology stack of ten years plus - not to mention the engineering skill set - is Microsoft based. That’s why we’ve tried to strike that happy medium with the Rails-inspired monorail dotnet libraries. That said however I was so impressed by the interview I’m going to be reinstalling RoR on an Ubuntu partition to re-investigate the tool. I want to learn more of the details about something that was created by a person who thinks the way David does.

As a guy who has spent much of his career maintaining other peoples code, the fact is that no one writes code simple enough for it to be self documenting. And something that is self-documenting to you as the author is not necessarily self-documenting to a later developer that has to fix/enhance the code. Self-documenting code is a means to an end for many developers….where the end is they don’t want to write comments and they fool themselves into thinking that there “beautifully written code” is the means.

Hi Bob!

I hear where you’re coming from and I’ve been in that situation myself. But a critical question I’d have to ask is if you were going to make fixes and enhancements to a project would you want it to be one that was well documented or well written?

I think that’s the pivot point that sells the philosophy. If you have a pile of poorly arranged undocumented code I’d far prefer the original author spend their time refactoring for simplicity and clarity than leave the actual code intact and “document” it with comments.

Something that helps is to explain what beautifully written code implies. It’s a very abstract concept but here are some examples based on bad habits I’ve moved away from over the years as well.

Don’t shorten variable names or parameter names. Spell it out. Modern editors save you the keystrokes so you’re only helping yourself and others by having big beautiful variable names. If you have a variable named “idx” and “list” those requires a comments, but if you have a variables named RemoveMarketOrderIndex and a MarketOrderList the comment becomes redundant.

// A list of market orders
IList list;

// A list of market orders
IList MarketOrderList;

Another example is don’t put conditions and loops in a function to a point where you can’t see the end of a functional block from it’s beginning in a screen or two. That is to say try to keep each function on one screen, or maybe two, but avoid making something so big you’re paging up and down nonstop to see what it’s doing. Also on those lines don’t go deep into nested try/if/for blocks in a function if you can.

Say you have a function that has a try/catch that acquires a collection from a source and has a for loop that recalculates part of the information. If the whole function can’t fit on screen then tear out the insides of the for loop into an actual function and give it a name that describes what it does. Also tear our the data acquisition code and put it into a function named after what it does.

Know what I mean? You could comment the hell out of the single-huge-function (making it even bigger) or you could spend that time refactoring out a function named “RecalculateYearToDatePriceChange” then you win on both ends. The outer function now contains a small, tight try/catch around a fetch-data call and a for loop that calls a function whose name tells you what it’s doing.

The inner function now has a clear name describing what it does, and that’s all it does. It contains the business logic to recalculate. Now there I’d say is a good place to have comments to describe the specifics about the domain logic. Like you would say :

//year to date is always based on the first monday in january to the monday prior to the current date.

Now THAT’s some documentation you want to put in context in your code, rather then rely on some well written date-math to represent the rule behind the code.

So in a nutshell the comments and documentation should describe the business logic or specifics of the problem domain. If your comments are needed to describe code that can’t be understood otherwise - that’s code that has to go.