Archive for category Design

Red Pen and Comments in the Margin for your UI

Do you remember how your High School English teacher graded your papers?  Mine all used red pen and circled things and wrote comments in the margin.  I still do this today when I write something important.  I print a copy, grab a red pen, and turn into a ruthless editor on the lookout for just a few simple things, like using fewer words.

But red pen and comments in the margin doesn’t only apply to writing.  You can apply the same principles and concepts to a user interface.  Take a screenshot of your application, print it out, and find yourself a red Bic.  There’s something special about writing on and drawing over an image of your application because it’s something you probably never do.  Editing a screenshot in Photoshop is good, too, though sometimes not as satisfying.

Working example

Below is a before and after screenshot of a single sidebar in FoodHub Pro that shows my Red Pen and Comments in the Margin thinking.  My software is constantly evolving and improving, and there’s no need to let ego get in the way of a great UI.  It might be that this sidebar could be refined further if we find that users don’t actually need all of the widgets.

The “After” image has fewer words, fewer lines, no distracting headers, and is shorter overall with no loss of functionality.

Use a Red Pen and Comments in the Margin and let me know how your UI turns out.  I’d love to see more before/after examples.


FoodHub Pro sidebar with "red pen and comments in the margin" editing

#1:  Use fewer words

How many times have you heard someone explaining something and they said “What that means is …”  These words don’t say anything.  Just say what it means, don’t preempt.

What that means is be thrifty with words.”

The first four words mean nothing and the last four mean everything.  Take your red pen and cross through half of that sentence.

What words can I cut from my sidebar?  ”New Purchase Order” and “Choose a grower …” can be concisely written as “New PO for grower …”  That’s a 33% word discount!

#2:  Avoid clutter

Don’t make me think, don’t make me read, and especially don’t hide the few words I must read beneath words I want to ignore.

The headers in my sidebar have no purpose other than to be bigger and bolder than the words that have meaning, like the “From” and “to” labels and “Show only” which implies filtering capability.

#3:  Remove stuff

Do we really need headers?  Headers are generally meant to delineate blocks of stuff, which I think it particularly well suited by wells.  Headers are big, bold words that aren’t important.  They are too tall.  Wells, on the other hand, provide excellent delineation of things and implies depth on a page.   With fewer meaningful words remaining in a well, the purpose of the widget becomes obvious and you don’t need a header to explain what it is.

Are there any form fields that aren’t really needed?  Our customers don’t change business models very often (read: never), which means the type of Purchase Order created never changed.  We tucked that option away on a config screen and dropped it from our form.  It simply wasn’t needed.

The Results Have Been Measured

Without any loss of functionality and with an immeasurable increase in clarity and simplicity, we can measure results by counting what remains.

  1. 30% of words removed
  2. 100% of tall and bold headers removed
  3. 100% of bold form field headers removed
  4. 0% change in distinct widgets with wells replacing horizontal lines
  5. 0% loss of functionality
  6. Increased clarity and simplicity:  immeasurable

Red Pen and Comments in the Margin works as well for interface design as it did for my old English teacher.  It cuts through clutter and simplifies by eliminating anything that doesn’t directly and succinctly address the task at hand.  Everything in the design is subject for removal, from redundant or unnecessary words to unused elements to the use of white space.  Each item in a design should fight for its life because a good editor always has a red pen handy.

“Don’t Make Me Think” applies to your code, too

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:

  • Code in plain English. Use an active voice (just like writing). What do you think this method does?
  • dao.findCustomerBy(order);

    Or what about this if statement?

       // allow...

    or better yet…

       // allow...

    The pretty method on the Admin class looks like this:

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

  • Make Stuff Obvious. Quick, what does this line of code do?
  • 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: (it’s Free software). Use Java 5’s static imports to make the short date seen above.

  • Be Merciless. Be your own worst critic when reviewing your code. Always strive to improve what you’ve written. Just as great essays and novels (and books like “Don’t Make Me Think”) require several rounds of editing, so too does your code.
  • Never nest ternary statements. ’nuff said.
  • Write comments, but be brief and explain why your code does what it does, not how it does it. We already know how it does it, we’re looking at the code.
  • 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.

    Printable Design Patterns Quick Reference Cards

    The Gang of Four design patterns have been elegantly distilled into a quick reference guide suitable for printing on 8.5 x 11.

    You can get a larger version for your office wall, too. Check out the poster size. It’s perfect for any software organization.

    I’ve posted low-resolution versions of the two cards here with the author’s permission. Links to the high-res printable versions are below on the author’s website.

    designpatterns2_sm.jpg designpatterns1_sm.jpg

    Jason McDonald created these high-quality reference cards. Click here to view the printable high-resolution images.

    Horses for courses

    Pick the right tool for the job.  It can save you a lot of time and effort.  This article explains how I replaced dozens of Java class files, an XSD, myriad library dependencies, a build script and a whole lot of complexity with 40 lines of Python.

    A friend of mine recently bemoaned my use of the term “pick the right tool for the job.” Apparently, he thinks it’s a tired metaphor and a boring cliche. And so in deference to my friend, I will instead talk about choosing the right horse for the course.

    Some horses are mudders, some are good at short-distance sprints, still others are the ones you want for the long race. If you’re eying the race’s purse, you choose the right horse for the course.

    So, how do you choose the right horse? I’m guessing it has something to do with experience, breadth of knowledge, and understanding when a functional program makes more sense than an imperative one or knowing when a script is better than a fully engineered OO implementation. Here’s an example to fan the Java vs. Python flames.

    Not too long ago, in my previous life working for a consulting company, I wrote a small Java application to monitor our many web applications. The requirements were simple: the server page should return “OK” (text/plain) else the contents of the entire page would be mailed to a list of interested recipients. This technique allows a developer to put whatever test they want in their server page (database connectivity, unit tests, whatever) knowing that any exception they write to the page would be mailed to them.

    Not hard, right? Easy implementation? It was both times I wrote it, but one of them was a much better horse for the course.

    The configuration file in Java was XML, natch, which required an XSD. The XSD required JAXB(or Castor, XMLBeans, etc.) to generate bindings for the XML. The Main program was well factored in that each class did one thing well. As a result, I had a class to poll a site, one of load the configuration, a class to send email, etc. Between Main and classes from Castor, I was up to a dozen .java files. Main, of course, required libraries (Castor, mail.jar, activation.jar, etc.), and those libraries required a script (.cmd in our case) to load them all onto the classpath. Oh, let’s not forget about building with Ant. Add a build file to the heap.

    It worked, but damn, that’s a lot of files and jars and complexity for a simple monitoring program!

    I rewrote it in Python in less than 40 lines of code. Two files. There are more comment lines than executable code.

    Choose the right horse for the course. Occam’s Razor says the 40 line solution is the right one, but you can decide for yourself.

    Here’s the python program and configuration file.

    Many developers learn one or two mainstream languages and always run their favorite horse, irrespective of course. The best developers will be those that love learning new languages and techniques. I’m a better Java programmer today because of what I’ve learned from Python. I’m a better web developer today because of what I’ve learned from Ruby on Rails.

    Learn more. Broaden your horizons. Try new things and new styles of development. Learn to pick the best horse for the course. Always use the right tool for the job.

    Tags: , , ,

    Switch to our mobile site