Beautiful Code [341]
Project libxslt from the GNOME project has helped breathe fresh life into William Perry's Emacs W3 browser; Emacs W3 was one of the early HTML rendering engines, but the code has not been updated in over eight years. That the W3 code base is still usable and extensible bears testimony to the flexibility and power afforded by Lisp as the implementation language.
Code in Motion > On Being "Bookish"
32. Code in Motion
Laura Wingerd and Christopher Seiwald
The main point is that every successful piece of software has an extended life in which it is worked on by a succession of programmers and designers….
Bjarne Stroustrup
Early in the planning of this book, greg wilson asked contributors whether Beautiful Code was an apt title. "Much of what you're going to discuss is software design and architecture, rather than code per se," he wrote us.
But this chapter is about the code. It's not about what the code does, nor is it about how beautifully it does it. Instead, this chapter is about how the code looks: specifically, how certain human-visible traits of coding make serial collaboration possible. It's about the beauty of "code in motion."
What you're about to read is borrowed largely from Christopher Seiwald's article, "The Seven Pillars of Pretty Code."[*] In a nutshell, the Seven Pillars are:
[*] The article is available on the Perforce web site: http://www.perforce.com/perforce/papers/prettycode.html
Being "bookish"
Making alike look alike
Overcoming indentation
Disentangling code blocks
Commenting code blocks
Decluttering
Blending in with existing style
While these may sound like mere coding conventions, they're more than that. They're the outward manifestations of a coding practice that keeps product evolution in mind.
In this chapter, we'll see how the Seven Pillars have supported a piece of code that has been part of a commercial software system for over 10 years. That piece of code is DiffMerge, a component of the Perforce software configuration management system. DiffMerge's job is to produce a classic three-way merge, comparing two versions of a text file ("leg 1" and "leg 2") to a reference version ("the base"). The output interleaves lines of the input files with placeholders marking the lines that conflict. If you've used Perforce, you've seen DiffMerge at work in the p4 resolve command and in Perforce's graphical merge tools.
DiffMerge was originally written in 1996. Despite its simple goal, a three-way text merge function turns out to be fraught with intricacy. It's a melting pot of special cases arising from the idiosyncrasies of user interfaces, character encodings, programming languages, and programmers themselves. ("That's not a conflict." "Yes, it is." "No, it's not!")
Over the years DiffMerge has become a locus of significant development at Perforce Software. So, it's not good enough that DiffMerge is simply a correct piece of code. It has to be a piece of code that "plays nice" with the tools we use for coding, debugging, and change management. And it has to be a piece of code that anticipates being changed.
The road from DiffMerge's first implementation to its present-day form has been uneven, to say the least. It's probably no coincidence that the further we strayed from the Seven Pillars, the rockier the road became. Later in this chapter, we'll reveal some of the potholes (and one major wreck) that beset DiffMerge's 10-year journey.
All's well that ends well, however. Today's DiffMerge, reprinted at http://www.perforce.com/beautifulcode, is stable and accepts enhancements with ease. It is a demonstration of how coding in anticipation of future change can produce a beautiful piece of code in motion.
32.1. On Being "Bookish"
"The Seven Pillars of Pretty Code" describes guidelines we use at Perforce Software. The Seven Pillars[] aren't the only coding guidelines we use, nor are they applied to all of our development projects. We apply them to