When perfect code gets FUBAR - and how to avoid it!

You’re a confident coder. Your JavaScript is polite, humble and never intrusive. Your CSS is flexible yet robust, and your HTML is arranged with such beauty that Rev Burners-Lee would bow in admiration. And, you’ve just finished coding your magnum opus. Nimble, responsive, elegant and accessible. You lean back in your chair, hands folded behind your head, as you proudly click “send” as a fellow coder begins to incorporate your code into the CMS. You look forward to the day a few weeks from now, where, in response to your site going live, a double rainbow forms overhead, Republicans agree to co-sign a bill guaranteeing universal healthcare, and Lauren Hill releases her follow-up album.

However, as the launch draws near you take a peek at the progress and notice that everything is in a complete state of chaos. You see list tags wrapped in divs, your beautiful microformats have been ransacked, and nefarious onclicks pepper the code like a burgeoning fungus.

Face, meet Palm.

Wincing, you try to figure out what happened? Was it an issue with communication, lack of documentation, client education, CMS bullying? All the while, you’re wondering if it’s even worth attempting to fix. Well, anxious reader, the answer is an emphatic “Yes!” And it’s not as daunting as you might think...

Damage limitation

First things first though. We’re going to need to have a little time-out. Take a deep breath. Hold It. Exhale slowly. Repeat.

Next, understand there are some things you will not be able to resolve or fix.

Some of these errors will make it to production. Some may even be egregious, for which you may face public shaming from an internet troll sporting an ironic nerd-shirt and spewing forth condescension from the security of their mother’s basement.

Now, in life some people have good intentions but for whatever reason will let you down. Others, to put it delicately, have unresolved, misguided intentions stemming from childhood, and will also let you down. Then there are the honey badgers of web development, the notorious Content Management Systems, designed to kill all your hopes and dreams.

I am aware that some of you are required to work with a certain CMS that wraps each entire page in a <form> tag. I feel you. Your pain is real, and you most definitely aren’t paid enough. The calling of a coding zealot requires the willingness to carry a heavy yoke. The important thing is to recognise this inherent tension so you can soothe the raging inner child and set about the task of addressing the issues you can fix.

Develop a rapport

The most crucial thing to understand on any project is that the path to success begins well before you fire up your code editor. From the first interactions you’re having with people you are building rapport. Rapport is your friend. Rapport is the freshly ground, aero-pressed, floral yet pleasantly acidic morning cup of coffee that sets the tone for the rest of your day. When you’re in the position of giving correction, context is everything. And having good rapport can mean the difference between sounding helpful and sounding condescending. Fortunately there’s a litany of things you can do during the course of a relationship to build rapport:

1. Make yourself available, in person, as soon as possible. Or if distance is an issue, schedule a call. The anonymous nature of the web makes it easy to revel in obscurity but when you’re building towards collaboration, the more you make yourself known the more trust you gain.
2. If a contract or other “business” document is involved make it human-readable. Contracts are scary and intimidating. Contracts that are verbose and obscure scare people even more. Fear is the path to the dark side. A human-readable contract helps assure people that you’re not a robot, and that you can relate to them.
3. Listen. Ask any counsellor; the strongest path to gaining a person’s trust is to assure them you’re listening. Let them know you understand where they’re coming from.
4. Emphasise and assimilate common ground. If they’ve got some habits or practices that resonate with you, implement them into your process. They’ll LOVE you for it.

Build from standards

Still, if the thought of interacting personally with real people has your palms sweating, fret not dear web-inclined anthrophobe. We’ll now move to some more concrete tools you can implement to help thwart code curmudgeoning. The best first-step you can take towards productive hand-offs is to build from recognised web standards. This immediately gets you three things:

1. A convention that many coders are already following
2. Documentation that you didn’t have to write (though be aware that some documentation is painstakingly verbose - W3C I’m looking at you)
3. A community of voices you can point to in the case of push-back

In addition there are many widely regarded frameworks and conventions that can bring further consistency to a project such as Microformats, LESS, Blueprint, WAI-ARIA, WCAG, JSLint, as well as best practices such as keeping your content layer separate and your scripts lean and modular. The ubiquity of standards across the web provides an easy first-step for colleagues and clients to align with a consistent process for coding.

Work to a style guide

Call it a hunch, but I’m willing to bet you’re already on board with standards. But a standard only works when it’s in use, so how does one go about ensuring compliance and cohesion across a project?

For that I offer you the technical style guide. In the world of graphic design, a style guide’s purpose is to ensure that the design is interpreted correctly and to address many of the gaps that will appear as the design is applied across the many diverse pages of a site. Any graphic designer worth their plimsolls and horn-rimmed glasses offers a style guide for precisely this purpose. Why should code be any different?

You no doubt have all sorts of conventions that you’ve created and adhered to in the development of your code, but don’t assume those structures and paradigms are going to be obvious to the receiver. Graphic style guides can range from a few simple pages to formal leather-bound treatise. Yours should likewise differ according to the scope of the project and the range of folks tinkling with your work. As a starting place, your code delivery should include a basic guide describing:

1. An outline off the base HTML document including comments which describe any included stylesheets and scripts
2. Global classes and their conventions
3. HTML best practices and caveats (especially if they pertain to implementation in a WYSIWYG)
4. A list of functions available and their options (especially any related to form validation)

Similar to the design world, your follow coders are also going to have a lot of gaps to fill. Providing them with a checklist and a road map, in the form of a technical style guide, dramatically increases the probability that your coding efforts will maintain course.

You work hard on your code. Don’t let it go to waste. Work on rapport with your clients and contributors to mitigate tension and build a foundation for healthy collaboration. Then implement some simple standards and practices to shape the path. Above all, don’t wig out when our code isn’t perfect. It's probably never going to be. But with a little attention to the persons and processes of your fellow coders, it can and will get better.

If you liked this article, please be sure to vote for Scott's SXSW panel proposal, Shit Code: When Good Code is Betrayed! Voting ends 11:59 CDT on Friday, September 2.