Interface Design Under the Hood

The philosophy that a web site ought to be designed with human users in mind is (thankfully) well-entrenched into the thinking of modern web design.  But I think that it ought to apply to the whole web site.

Any designer worth his or her weight in pixels spends a lot of thought not just designing a pretty display, but also thinking like their eventual users: making the presentation clear and the navigation intuitive. After all, we build web sites for people, not the computers that run them.

But there is another user of your web site that usually goes completely unconsidered.  The interface for this user is virtually always left in a state decipherable by only those few who had their hands on it during construction.

The forgotten user is anyone who follows you. Including yourself. The forgotten interface? The code.

With all of the justifiably righteous attention paid to the public face of the web site, it would seem like a no-brainer that the same user-first philosophy would be a guidepost in the construction of the code base. But that’s rarely the case.

I don’t mean that it’s poorly written code, or that it has utilized a sub-standard framework, or sub-standard technologies. It could be the best of all possible worlds, written with sizzling textbook perfection.

And yet, how common is it to spend twenty minutes tracking down a line of code, buried in a sea of similar-looking lines, or tucked perfectly away in an include, or stored in some component of the framework.  Even if it’s your own code, written only a few weeks or a few months before?

How much time do you spend looking at another developer’s code, making sense of where some set of client-requested changes need to be made? We’ve all seen it. Code soup is not just a product of bad developers. It’s a product of language written with a machine (or a textbook) in mind, written in a hurry, or written in the fuzzy flurry of the dog days of any get-it-done-tomorrow web project.

So I submit that code should be written not just for the machine, but also (perhaps primarily) for the developers who follow you – including you.

The Obvious, Title-inspiring Example

Let me make this case by inviting you to look under the hood of your car, at the physical equivalent of the code we write. The interior, the dashboard, and shiny paint job are the graphic design and user interface of your car. Polished and perfected for people to look at and make easy use of. But under the hood? That’s code. It’s machine parts doing the work of machine parts. And it’s designed functionally, precisely, and (typically) still with human beings in mind.

The radiator cap, oil cap, battery, and other high-maintenance parts are accessible and labeled. The battery is placed where it can be jump-started. The oil pan is placed where it can be drained. The gas tank isn’t accessible – it doesn’t need to be – but the gas cap is exactly where a human being will need it.

The elements under the hood of your car don’t need to be positioned that way to make the car operate. In fact, it’s easy to imagine that a perfectly designed engine might not have an accessible battery, oil cap, filters, spark plugs, or any labels at all. Elements may be tucked under other elements to limit the amount of tubes and wires and such between them.

But they’re not. They’re designed with the full understanding that the needs of the technology must compromise with the need of the few human beings who will need to operate under the hood.

And those of us who write code should follow the same example.

Suggestions

• Use comments religiously. They are easy little signposts to leave for yourself and others. Consider using comments to:
• Mark the beginning and the end tags of a <div> element. Frequently, a page ends in </div> soup. Knowing which ends which can save a lot of time.
• Explain browser hacks, specific to the browser and the intended effect
• Identify the color of hex values .for_example { color:#000; /* BLACK */ }
• Label include statements and add a super-brief overview of their contents
• Denote the position of related code in other files of a framework
• Leave notes for future developers where easy maintenance tips may help

Peppering your code with simple well-written, well-placed comments can save countless hours of maintenance time, especially when future developers come into the project fresh.  And remember, saving time means saving money.

Strong commenting can enable other members of your team (especially those with a lower level of programming knowledge as the code author) to participate in the project, where otherwise a bottleneck might occur as every new issue has to go back to the code author for a solution - slowing down the project and limiting the inclusion of the rest of the technical team.

And commenting can also serve as a self-check on why you’re doing things in the first place. Leaving a note about a browser hack might occasionally shine a light on the fact that you’re using a hack. Maybe there’s a better way. If something is worth a comment, maybe it’s worth a considering a simpler alternative that does not need explanation.

• Use multiple blanks lines to visually separate different sections of code. Just like a graphical design uses white space to keep elements from running together, you can use white space in your code to make it easy to see where one section ends and another begins.
  
  Purists may tell you that blank lines and copious comments increase page length and perhaps file size, and cause the server and/or the browser to do extra work when processing the code. That’s true. But it’s hogwash. Modern sites aren’t run on Commodore 64s, and we’re not talking about writing War and Peace in between every if/then statement. We’re talking about a few extra kilobytes (at best) which will virtually always pass unnoticed in any real-world use.
• Use includes (or the equivalent) wherever possible, provided the include files are accessible and thoroughly logical. A good use of an include is any section of code that is identical on multiple pages of your site. Using includes makes maintenance easier and shortens the length of your code on the pages where they are used.
• Indent the lines of those sections of your code where a little horizontal separation can help identify it as a self-contained element.  You may choose to do this for an entire section of code, or for the second and subsequent lines of a section, to show that it belongs to the first, un-indented line.  However, be careful with this technique. Too much indenting can lead to a chaotic looking page of code, especially if excessive text wrap needlessly brings the ends of lines around to the left side of your window.
• Make decisions and stay consistent about the use of capitals, dashes, underscores, initial caps, etc. in your statements.  Consider the following suggestions:
• Use all caps for comments (they shout, so use them where you want to communicate above the level of the code itself /* PAY ATTENTION TO THIS */), and limit the use of caps elsewhere.
• Use underscores instead of dashes in file names, ids, and classes. Dashes are smaller and higher, so they don’t visually separate from the alphanumeric characters around them the way that the wider, lower underscore does.
  
  Avoid initial caps in filenames especially, but also throughout your code. In filenames, you can run into case-sensitivity issues that are simple to solve, but you have other bugs to track down, don’t you? Elsewhere in your code, initial caps add a small extra dimension of complexity, and will also tend to visually blend your markup into the content it surrounds.  Separating the markup from the content in any way possible, even on such slight visual grounds, is always a good thing.
• Don’t use dots in any naming convention. No good things can come of it. It’ll confuse file extensions, class definitions, and a whole host of other fodder for all night debuggery. Besides which, they’re small and hard to see.

Leadership

It’s important when multiple developers are working on a project, that some leadership is enforced, to keep the team employing the same tactics with the same consistency across the board. If one team member is doing what she think makes sense, and another team member is doing what he thinks makes sense, it’s highly likely that the two will end up with a cacophony of stylistic choices that only leave the same level of confusion they were both working against.

The Logical Progression of UI

Bringing the principles of user interface to the code base just makes sense. It’s another step in the web’s lifelong battle to fight confusion and complexity, and to promote inclusion and standards.

It’s not enough to write great code – no more than it would be enough to build a great engine for a great car. People have to work under the hood. Not just you. Maybe not even just your team. Maybe your clients, or their future employees or vendors. Maybe others.

In the language of the web, these people are users. They are humans. Our code should be written and presented with them as the priority, just as the front-end was written and presented. 

[Link to Interface Design Under the Hood]