Style Guide

We may have to evolve a more formal style guide, but here are a few notes.

First off, these rules are useful: Pike Style

• Harvey style is to minimize use of the C preprocessor. I really like this a lot, though it took getting used to. I really wish we had followed these rules in coreboot, but memory constraints of small flash parts made it impossible at the time (2001).

So, instead of stuff like this:

#define X 0
#if defined(X) && x
   y(z);
#endif

In Harvey you'll see:

if (X)
	y(z);

This makes sure that:

• y will always compile (it's awful to enable debugging and have things stop compiling; it's also common in much code)
• the call to y is easy to turn on
• when you look at the call to y, it really is C code it's referencing, not some cpp macro

A few more notes: Ken C removed uncalled code at link time. There is no cost in Ken c to

if (0) { something}

or

if (0) y(z);

gcc is getting there but not yet. Nevertheless, avoid cpp tricks commonly used in other projects. cpp defines constants and does includes, not much more.

• Avoid compiling debug code in or out if you can. Russ pointed this out to us in the early going on 9p for linux. It's painful to have to recompile to enable debugging.

So, NOT

#define X 0
if (X) whatever();

DO THIS:

int X; // iniitalized to 0
if (X) whatever();

Then, while debugging, you can turn things on.

• Avoid inline assembly. Harvey has only a few hundred lines of assembly, and you know where to find it. Processors and toolchains (esp. clang) are smart about inlining things where needed; let the toolchain work that stuff out.

• Avoid inlines at all. Most of the time, people get that wrong. Even if it's right at first, it can be wrong later, and who will know?

• Avoid any gcc-specific hacks. Harvey is leaving behind one non-standard C compiler and we don't want to adopt another one. Harvey should work fine on gcc, clang and icc. MINIX has done this and we can too.

• Finally, look at the mmu code. Most of it is in 9/port. It's a very careful dance between the portable part and the architecture-specific part, and it's a masterpiece of design. You can see how portable and architecture dependent parts are woven together. It's why amd64/mmu.c is one file and why I could change the x86 code to a new architecture in one evening. It's worth learning and it provides a pattern for how to write in Harvey.

There's one exception I've found to the cpp hackery rule, and that's jmk's DBG macros, of which more later. But that maybe should be our one exception.

We can add to this as needs dictate.