ronin coder

I’ve switched jobs twice in the last 12 months. It’s certainly not unheard of in my trade to bounce around a bit, and it’s not the first time I’ve had the experience. It has, however, reminded me of many of the unique challenges associated with trying to quickly get up to speed with a body of existing code, and especially those idioms and misfeatures which most complicate the ramp-up process.

Since most of what I work on these days is web application code, the issues below will be focused there, but most of the basic concepts should hold true for most any type of programming.

So, here are my top three recommendations for anyone who expects other people to have to eventually read or maintain their webapp code:

Logic/template separation

Web developers need to be willing to switch between 4-5 languages from moment to moment: HTML, CSS, JS, SQL, and a general-purpose language for business logic. That being said, for the sake of all who will read your code after you write it (including your future self), avoid interleaving languages arbitrarily within a single logical block of code (method, source file, or module).

I still routinely see markup, Javascript, and Python/PHP/Ruby code mixed in the same source file, usually with one language nested inside a loop defined in a another, emitting yet another syntax for consumption by the browser.

If you’re generating dynamic Javascript, create a JSON array which can be iterated over by plain, static JS code, rather than interpolating values directly into JS method calls. Similarly, when producing HTML, minimize the logic in the “template” sections of code. If you’re interleaving database queries, ‘foreach’ loops, and emission of <tr> and <li> elements, it will be nigh-impossible to change the business logic being used without also breaking the layout, and visa versa.

Commented code blocks

If you’re using version control, there should be no need to leave large blocks of code commented out or disabled. (If you’re not using version control, stop reading this immediately and go buy a book on Subversion, Git, or Mercurial. Come back when you have your version control workflow established.) Commit messages, revision diffs, branches, and supplementary documentation (such as a team wiki, another tool in the “must have” category) should provide a sufficient amount of sideband communication about proposed or unfinished code.

If you leave large amounts of inactive code lying around, on the other hand, you’re encouraging bit-rot and cargo-cult design. Your commented-out code will not have test coverage, or be kept up to date with internal API and schema changes.

None of this applies to example code — usage tips provided in comment blocks for documentation purposes are handy, as long as they’re kept up to date. I object specifically to operational code which is disabled en masse rather than removed.

Conventional coding

Even after settling on a programming language and framework, most teams still have a lot of leeway in terms of how to structure their code. Naming conventions, whitespace, inline documentation, and module layout are usually left largely up to you. However, there are some major benefits you can realize simply by imposing some basic rules for consistent coding style across your entire project.

You should start with basic syntactic conventions: 4-space tabstops, braces in K&R style, class names in StudlyCaps, etc. At some point, you may want to make a full cleanup pass across your codebase that does nothing but enforce these standards to avoid polluting your working patches with simple readability cleanups.

From there you can move on to more semantically-meaningful rules: no mutable global variables, JavaDoc/PHPDoc/Python ReST Docstrings for all public API entry points, use bind params instead of string interpolation when building SQL queries, etc.

The payoff

As you move through the code making these changes, you’ll find certain regular and repeated patterns emerge as the line noise of differing style and sloppy coding evaporates. Now you’re ready to start refactoring. Lift duplicated code into utility functions, bundle those functions into classes with shared state or domain knowledge, and then arrange those classes into useful packages.

Most of the responsibility for these tasks falls squarely on the shoulder of the development team. However, management has a critical role to play as well: when your developers begin grumbling about unmaintainable code, before giving them leave to start over or abandon existing working applications, press gently to see if a bit of housekeeping like what I’ve outlined above might let them work a little longer with the current implementation.

There are any number of reasons why an old implementation can and should be abandoned — obsolete technology, dramatically changed requirements, heavy turnover — but “ugly” or “messy” code shouldn’t be sufficient justification on its own.