The mythical man month

In the programming field, it’s pretty rare to find a book that’s still relevant even five years after it was published. The Mythical Man-Month is still useful forty years after it was first published, which is either amazing or depressing depending on how you look at it.

What depresses me about how useful the book still is so long after it was written is that in the forty years since, we clearly haven’t learned that much about how to run projects. I first tried to read The Mythical Man-Month ages ago, and I got so frustrated about how little we’ve learned since it was published that I had to set it down. Then I completely forgot about it for a few years because I’m just that organized :) I finally finished it this year, and it’s just as relevant as ever. By all rights everything in that book should be totally obvious and taken as a given by every project manager out there, but sadly it’s not. It is, however, kind of comforting to know that other people have run into the same problems I have.

The amazing part of The Mythical Man-Month is how clearly it shows that the actual programming is the easiest part. Code is simple compared to trying to coordinate a large team and hit a deadline, but as programmers we seem to get hung up on the easy part and largely ignore the hard part. One of the many terrible ironies of programming is that a field that attracts introverts who just want to be left alone to code actually requires huge amounts of communication if you want to get anything meaningful done. For me and probably for most other programmers the code is the fun part, so it’s understandable that we’re not as good at communication as we should be but eventually we’ll grow up as an industry, right?

As sarcastic as that sounds, I think a large part of what we need to do as an industry is accept that things just aren’t as easy as we wish they were and learn to work around it. It’s pretty similar to the way children grow up and understand that the world isn’t as simple as they thought and learn to work around it. I and every other programmer ever have massively underestimated how long something was going to take, and no doubt  we’ll all keep doing that. But understanding that underestimating tasks is common allows you to leave extra space in the schedule and/or prioritize features so you know what can be cut if you aren’t going to hit your deadline.

Basically we just need to learn to account for human nature. Should be easy :)

Underrated dev tool of the day

You might not expect it, but is actually a really useful dev tool. Like they say, naming things is one of two hard problems in computer science. When I have an object that’s difficult to think of a good name for, I just plug whatever vague description I have into and poke through synonyms until I find something I don’t hate. Try it, it really does make it easier to pick a name :)

The Visitor design pattern

Let’s talk about the visitor design pattern. This one is tough to find a real-world analog for, but once it clicks for you it can be really useful.

Basically the visitor pattern is used when you want to add functionality to an object or a set of objects without changing the object itself. If you have a list of objects and you want to perform a particular calculation on each one and might need to add more calculations later, you would use the visitor to ‘visit’ each one, get its state, and do the calculation. Headfirst design patterns uses the example of a menu item and an ingredient both needing a nutrition information report. It’s ugly to add essentially the same method to two classes and it violates the single responsibility principle to add a method that does something the base object shouldn’t know about.

Uncle Bob uses the example of building a report with data from hourly but not salaried employee objects. The employee object shouldn’t know anything about how to generate a line for that report or even whether it should be on the report at all, so it’s much cleaner to use a visitor to get each object’s data and use that to build the report.

So how does the visitor pattern actually work? First of all you need some interfaces or abstract classes for your other classes to inherit from. To keep using Uncle Bob’s employee example, you need an employee interface with an accept method that takes a visitor interface/base class as a parameter. Your visitor interface needs a visit method for each type of object it’s going to visit. Now that you have your interfaces set up, concrete employee classes like SalaryEmployee and HourlyEmployee can implement the accept method. All you need to do there is call visit(this) on the visitor that was passed in. Your concrete visitor class just needs to implement visit methods for each visited object and you’re done! There’s a nice clean class diagram here in case seeing it makes it easier to understand.

Why so many interfaces? Wouldn’t it be simpler just to call methods on the concrete objects directly? Not so much. We need an accept method on the employee interface so that the code that iterates over your list of employees and calls accept(visitor) on each one doesn’t have to know what type of employee it is. We need a visitor interface separate from the concrete class/es so that we can add more visitors without having to change the visited objects and because the visited objects shouldn’t be coupled to the visitor object. In the report example, the employee objects shouldn’t know anything about the visitor that compiles the report. To put the single responsibility principle another way, the report just isn’t any of the employee object’s business. If we decide to change the way that report is calculated or add another version of it, the employee object shouldn’t know or care.

Why not put the accept(visitor) method in the employee base class? Because then it would only be able to pass an Employee to the visitor, which is no good if different types of employees need to be treated differently. Yes, it’s duplicate code, but only a tiny little of it and in this case it’s necessary.

Aside from keeping your base objects from having multiple responsibilities, another thing the visitor pattern gives you is one class where all the related methods live. To stick with the report example a little longer, we’ve got all our report logic in one place instead of scattering it over different classes. Yay single responsibility! If we decide to change how we calculate rows in that report, we only have to change one class. If we only have two types of employees that may not sound like a big gain, but what if we need to add contractors and consultants and seasonal employees and part time employees?

The visitor pattern is a really weird concept at first but once you understand it, it can make your code a lot cleaner.

SICP: first impressions

Not so long ago I decided to try working my way through Structure and Interpretation of Computer Programs, hereafter referred to as SICP because that’s an awful lot of typing. Why SICP? Because I hear it will make me a better programmer and because I’ve heard about it enough times that I want to know what I’m missing :)

Thanks to the wonders of the internets, you can get the book at the link above and MIT-Scheme or SCM scheme. If you’re running windows like me, I don’t so much recommend MIT-Scheme. I have heard that it’s the only one you can do all of the exercises from SICP in (I haven’t gotten far enough into the book yet to see if that’s true, but I’ll let you all know when I do), but the documentation for it is kind of painful and in general I’d rather take up cottage cheese sculpture than learn emacs.

SCM is much less painful to run once you get it installed, but that isn’t as easy as it looks. The quick start for windows section currently says to install slib-3b4-1.exe and then scm-5f2-1.exe, but that’s the wrong version of slib. You want slib-3b5-1.exe from, then you can install scm successfully. After that make sure scm scheme has been added to your path, then you can use whatever editor you want to work with your scheme files and run them from the command line with scm -f <filename>

For an editor, I personally like Sublime, although I’ll be honest, I’m cheap and I think $70 is a bit steep for a text editor. It does have excellent plugin support though, as well as a much nicer interface than free editors like Notepad++.

If you decide to go with Sublime, I recommend installing Package Control and then the scheme package to add scheme syntax highlighting. Once you have package control installed, go to preferences->package control and click “Package Control: Install Package” in the menu that will pop up. It lags a little bit on my machine but in a second or two a new popup will appear that lists all the packages you can install. Search for scheme and install that package. Once you restart you’ll have scheme syntax highlighting and paren matching, which is pretty handy.

When you’re editing your scheme file, it will probably be helpful to know that you print to standard out with (display <arg>) and print a carriage return with (newline). You can skip printing your output if you use the MIT-Scheme interpreter, but then you’d have to use the MIT-Scheme interpreter :)

My workflow so far is edit in sublime, run the file with scm from the command line (scm -f <filename>, don’t forget), then look at the output and go back to sublime.

Now that the environment setup is out of the way, let’s talk about scheme. It’s been almost ten years since I touched any dialect of Lisp and it’s incredibly weird working with it again. Normally I write methods/functions from the top down, but scheme forces me to write them from the center out. It’s also pretty strange to work in a language with so little syntax. There’s almost nothing to scheme but a few basic functions and shit-ton of parens. It’s kind of beautiful, but compared to java’s creepy obsession with boilerplate it’s really, really weird. I don’t know yet if SICP will actually make me a better programmer, but it’s definitely forcing me to look at problems from a different perspective.

So far SICP has covered pretty basic parts of programming, but if it’s been a while since you used scheme I recommend plodding through the refresher. And check your work with google, there are a ton of solutions out there for all the exercises, including this handy wiki. There are a couple of tricky questions about normal-order and applicative-order in the first chapter that I got completely backwards the first time, so check your work and run an example to make sure you’ve got a handle on it.

Expect to hear a lot more about SICP from me in the future, I have plenty of chapters to go.

How javascript is like a board game

Javascript is much more like a board game than you might think. Let me tell you a story to explain what I mean.

I used to be convinced I just didn’t like board games. I’d played the usual Snakes and Ladders, Sorry, Risk and Monopoly as a kid, and I could happily go without playing any of them ever again. Especially Monopoly. At least the other ones had an end in sight, even in Risk there was the hope of a quick and merciful rout, but Monopoly always seemed to end with people forfeiting just to get the game over with.

Then friends of mine started introducing me to board games that didn’t suck. Games like Clue and Red November and Space Alert and Ticket to Ride. It turns out I like board games after all, I just don’t like shitty board games.

Javascript, as it turns out, is remarkably similar. I used to think javascript just sucked, then I started working with ember. It turns out I don’t hate javascript after all, I just hate shitty javascript. All of the javascript I’d worked with pre-ember was a totally structureless mess – which I freely admit was partially my own fault. The vast majority of my programming experience is in java using frameworks like struts and spring which enforce a lot of structure. Server devs, myself included, don’t always know what to do without a framework enforcing some structure on our code.

Ember is an extremely opinionated framework, which as a veteran of rigid java frameworks I find comforting and familiar :) It also takes quite a few architecture decisions out of the developer’s hands, which is tremendously helpful if you’re a server dev with no interest in reinventing the wheel. Ember certainly isn’t the right choice for every single project, but it works very well in the context I’ve used it in and lets me get my front end tasks done quickly so I can go back to the server side development I prefer.

The moral of the story, in case you haven’t been paying attention, is that before you decide something sucks make sure you’re not just using it wrong.

Just say no to clever code

I was reading John Sonmetz’s post 11 Rules All Programmers Should Live By and I wanted to expand on 2: Clever is the enemy of clear.

In some cases, you do need to write clever code. If you’re working on something that absolutely must be optimized as much as possible, fine, get clever. If you’re working on something that’s actually hard, like cache invalidation, knock yourself out. But if you’re working on plain old business software like probably 99% of coders out there, knock it off! In almost all cases clever code is just so much mental masturbation: all it accomplishes is making the coder feel good about how very clever they are. Except that writing clever code is actually stupid.

Why? Because the point of writing code is to solve a problem. Clever code, on the other hand, is a problem. Remember, the vast majority of development is maintenance, not greenfield development. It’s much, much more important for other people to be able to understand and modify your code than for you to gain whatever performance or flexibility you think your unmaintainable code is going to get you.

Your job is not to congratulate yourself on how clever you are, it’s to add features so the company can make money, fix bugs so the company can make money, pay down technical debt so that adding features and fixing bugs is easier and the company can make money, automate tedious stuff so humans can do more interesting things that make the company money, etc, etc. And yes, this advice obviously applies to open source as well. At a company, you can make people work on code they hate by paying them. In open source, not so much. If people don’t want that bugfix/new feature badly enough to tolerate the mess you made when you decided to be clever, they’ll remember they could also be doing literally anything else, and then go do that instead. I’ve seen code that made scrubbing the floor sound like a good time in comparison, and if I didn’t have to work on it I most certainly would not have.

Not only that, but clever code doesn’t even make you look clever. Anyone who can see the bigger picture or has ever done any maintenance thinks you’re a jerk and probably a dumb jerk at that. Like Einstein said, “If you can’t explain it simply, you don’t understand it well enough.” If you can’t code it simply, either you don’t understand it well enough or you’re not a good enough designer to make it simple. Do you really want to convince the next people who work on your code that you don’t know what you’re doing?

Clever code actively harms your codebase, slows development, and makes the people who maintain your code want to throw chairs at you. Just say no to clever code.