Mark Gregory Turansky

Don’t make me think. That’s how I feel about your code.

Or as Martin Fowler puts it:

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” -Martin Fowler, Refactoring: Improving the Design of Existing Code

You’ve reached a whole new level of mastery when you write for simplicity, elegance, and maintainability. This is done on purpose, and it’s hard to get right. Deadlines, schedules, pressure, and stress all encourage us to cut corners and adopt a “Git ‘er done!” mentality. But Abandonment of planning under pressure is one of software’s classic mistakes. It’s a cardinal sin.

How do you write simple and maintainable code? I’ve got a 3-step program for you:

Step 1: Admit that simple isn’t easy

Designing simple software is hard. It has to be done on purpose. You can’t accidentally find yourself with well-written code and an elegant solution, it has to be written that way on purpose.

This admission is a bedrock principle required for designing great software and products. If you can’t admit that simple is Hard Work™, you haven’t hit rock bottom yet by having to maintain code that would make readers of The Daily WTF blush.

Step 2: Read “Don’t Make Me Think”

Steve Krug’s excellent book “Don’t Make Me Think” is about website usability, yet it changed how I look at my code.

Why? Because Steve applied the same principles in his book to his book! And if it works in those two mediums, I thought it just might work for me, too, in my medium (code).

“Don’t Make Me Think” is very easily absorbed because he’s feeding you information in a readily accessible way. He wrote it simply on purpose, and I’m certain it took many more hours to edit than it did to write. Simple is hard.

Step 3: Practice simple everyday

There are innumerable decisions you make everyday that affect your project for better or worse. You need to recognize these as the opportunities they are. Here are a few things you can do every day:

dao.findCustomerBy(order);

Or what about this if statement?

if(admin.hasPermission(Permissions.VIEWFILE)){
   // allow...
}

or better yet…

if(admin.hasViewFilePermission()){
   // allow...
}

The pretty method on the Admin class looks like this:

public boolean hasViewFilePermission(){
   return hasPermission(Permissions.VIEWFILE);
}

Date dt = march(28, 1973);

When I’m reading through unit tests, I’d much rather see the above statement to create a date than the equivalent Java:

Calendar cal = Calendar.getInstance();
cal.set(Calendar.MONTH, Calendar.MARCH);
cal.set(Calendar.DATE, 28);
cal.set(Calendar.YEAR, 1973);
Date dt = cal.getTime();

You can find those convenient date methods here: dates.java (it’s Free software). Use Java 5’s static imports to make the short date seen above.

That’s it. Three steps to better code. Putting it into practice won’t be easy, but if you want to be a master of your craft you’ll embrace the challenge and write things simply on purpose. The people who follow you and maintain your code will appreciate it.

No one should work alone; not in design or planning or coding or any other aspect of software development. Why?

Nobody gets it right the first time. Nobody.

Moreover, different people have difference experience. I’d be foolish to think I could write something as good as someone who’s already done it. You cut down on rework issues but tapping into others’ experience. You get it closer to right the first time by having others help think through the issues surrounding a design, and often by watching over your shoulder as you write code. Even then, no one gets it exactly right the first time, but you won’t be nearly as far off as you would be by yourself.

Xtreme Programming advocates pair programming on all production code. Not all code needs to be written by a pair, in my opinion; most is just fine for a single programmer, but that programmer should never be coding in isolation. Everyone on my team is involved with 100% of the project. We all know everything that is going on and we can jump in at any spot. Any non-trivial code is discussed by the entire team so that we can understand the best path to take. Not only does this help find flaws earlier in the process, it also gives all team members a keen understanding of the entire project.

Two separate incidences came up today that drove the point home for me.

First, a co-worker and I were profiling a piece of slow production code. We found a bottleneck and discussed a solution. His original fix would have worked, but it wasn’t as elegant as another piece of code I was able to point to that faced a similar problem and had an elegant solution. We only came to the right solution because we were working together on the same problem.

Later, another teammate discussed a Spring classloading issue with me (It was a tricky issue surrounding the generation of classes in Hibernate in Spring and having more than one instance of this in the same classloader). He and another coder came up with a solution that would have worked around their problem, but I was able to talk about an experience I had nearly two years ago where I was asked to find and fix a disastrous memory leak in our production servers. Both issues involved class generation in Spring and Hibernate, and I was able to set them on a new path. They are going to tease apart the distinct pieces of software from the monolithic whole and deploy them as separate components on our message bus. All our components are deployed in isolated classloaders, which will solve their problem.

The older issue involved the constant instantiation/initialization of a Spring ApplicationContext, where each instance caused the generation of Spring proxy classes and Hibernate DOAs. Classes once loaded are never unloaded from a JVM. This was our memory leak. The issue manifested itself at login, and our QA department did not login thousands of times a day like our users do. Code complete doesn’t mean you’re done. You’ve got abuse your system to find bugs like this.

I can’t begin to count the number of times I’ve asked for help with the design of a tricky piece of code only to find I was going about it entirely the wrong way. Oftentimes, people with a fresh pair of eyes will see things differently than you do. This does, of course, require egoless programming and smart teammates. If don’t have either, well, you’re project has bigger problems than we can solve here.

Doesn’t all this review and pair programming and constant communication decrease productivity? I’d argue no. In fact, as an investment of time, it’s paying rich dividends in decreased maintenance costs, robust production deployments, and higher morale during a time when other projects are struggling to pay off their design debt. We’re swimming when most others are just trying to tread water.

I’ve done the solo thing. I’ve also lead or been part of smart teams with tight communication. Pair programming is always the natural result of open communication and egoless programming as the team works together.

I know which one I prefer. How about you?

Months ago, I rummaged through the bargain bin at Best Buy and found Risk (the board game) for the PC. I used to have a lot of fun with this with my friends when I was younger, so I thought “what the heck!” and bought it.

Being a board game geek, math nerd, and computer programmer, I wrote a program to calculate the odds of winning Risk™.  My program ran through all the scenarios thousands of times, spit out the data, and I made some charts in Excel.

Without further ado…

Here is a chart showing your odds of winning a fight in Risk™:

But what about after you win? How many armies can you expect to have left? This should be an important piece of your strategy.

Here is the chart showing your remaining armies after the battle:

You can download the source code for the program, too.  Here’s the link: Java program to caculate odds in Risk

This work is licensed under a
Creative Commons Attribution-Noncommercial-Share Alike 3.0 United States License.