Vviewpoints

DOI: 10.1145/1364782.1364791

Kode Vicious
Beautiful Code Exists,
If You Know Where to Look

Coding is his game, pleasantries distained.

Dear KV,

I’ve been reading your rants in Queue for a while now and I can’t help asking, is there any code you do like? You always seem so negative; I really wonder if you actually believe the world of programming is such an ugly place or if there is, somewhere, some happy place that you go to but never tell your readers about.

a happy Programmer

Dear mr. happy,

While I will try not to take exception to your calling my writings “rants,” I have to say that I am surprised by your question. KV is a happy, cheerful, outgoing kind of guy who not only has a “happy place,” but also carries it with him wherever he goes, sharing joy and laughter with everyone around him and giving sweets to small children. (cough)

Now that I’ve bleached my brain, I can answer a bit more honestly. Yes, in fact, there are good systems and I have seen good code, sometimes even great code, in my time. I would like to describe one such chunk of good code right now. Unfortunately, it will require a bit of background to explain what the code is, but please stick with me. Perhaps you can relax by going to your “happy place” first.

One of my recent projects has been to extend support for something called hardware performance monitoring counters (hwpmc) on FreeBSD, the op-

erating system I work on. As the name indicates, hwpmc is implemented in hardware, and in this case hardware means on the CPU. I don’t know if you’ve ever read CPU or chip documentation, but there is little in our industry that is more difficult to write or less pleasant to read. It’s bad enough that the subject is as dry as the surface of the moon, but it’s much worse because the people who write such documentation either don’t understand the technology or are terrible writers, and often there is a fatal combination of the two. Starting from that base, the typical software engineer produces code that somewhat mirrors the specification, and as things that grow in poison soil themselves become poison, the code is often as confusing as the specification.

What is hwpmc? It is a set of counters that reside on the CPU that can record various types of events of interest to engineers. If you want to know if your code is thrashing the L2 cache or if the compiler is generating sub-optimal code that’s messing up the pipeline, this is a system you want to use. Though these things may seem esoteric, if you’re working on high-performance computing, they’re vitally important. As you might imagine, such counters are CPU specific, but not just by company, with Intel being different from AMD: even the model of CPU bears on the counters that are present, as well as how they are accessed.

The sections covering hwpmc in Intel’s current manual, Intel® 64 and

IA- 32 Architectures Software Developer’s Manual Volume 3B: System Programming Guide, Part 2, encompass 249 pages: 81 to describe the various systems on various chips and 168 to cover all the counters you can use on the chips. That’s a decent-size novel, but of course without the interesting story line. Kudos to Intel’s tech writers, as this is not the worst chip manual I have ever read, but I would still rather have been reading something else. Once I had read through all of this background material, I was a bit worried about what I would see when I opened the file.

But I wasn’t too worried, because I knew the programmer who wrote the code personally. He’s a very diligent engineer who not only is a good coder but also can explain what he has done and why. When I told him that I would be trying to add more chip models to the system he wrote, he sent me a 1,300-word email message detailing just how to add support for new chips and counters to the system.

What’s so great about this software? Well, let’s look at a few snippets of the code. It’s important to always read the header files before the code, because header files are where the structures are defined. If the structures aren’t defined in the header file, you’re doomed from the start. Looking at the top of the very first header file I opened we see the code snippet shown in Figure 1. Why do these lines indicate quality code to me? Is it the capitalization? Spacing? Use of tabs? No, of course not! It’s the