Introduction

These are notes for people working on programming projects with me. They outline what I expect as far as the mechanics of the actual programming is concerned. For more in-depth philosophy on many of these points, you are strongly encouraged to read Kernighan and Pike's The Practice of Programming.

Style

Programmers will always argue about stylistic minutia: naming, white space, brace placement, return value conventions, and so on. Which conventions are correct? Writing a program from scratch, there are many right answers. When you work on code someone else wrote and maintains, there is only one right answer: do what the rest of the code does. There is little that annoys me more than opening up a source file and seeing a section of code that looks nothing like the rest of the file.

If you are working with Plan 9 code, note the following conventions:

• no white space before opening braces
• no braces around single-line blocks (e.g., in if, for, while)
• integer-valued functions return –1 on error
• variable and function names all lowercase, no underscores
• enum or #defined constants Uppercase or UPPERCASE
• struct names Uppercase, with matching typedefs
• automatic variables (local variables inside a function) are not initialized at declaration

Language is idiomatic. If you use the same idioms as everyone else, your code will look natural. If you don't, your code will stand out like an American tourist in a foreign country. If you are writing something common, say it the same way everyone else does. For example, use a < 0 instead of 0 > a and name your loop variables i, j, k, not lv1, lv2, lv3.

Comments

If your code is readable, you shouldn't need many comments. A line or two comment above a function explaining what it does is always welcome.

Whenever you find yourself wondering why some section of the code is the way it is, add a comment, even one that says

      /*
       * BUG explain this.  I don't understand why the third parameter is 0 here
       * rather than -1.  I would expect -1 because ...
       */

Don't use commenting as an excuse for writing confusing code. Rewrite the code to make it clear.

Efficiency

Do the simple thing. Don't optimize unless the code is measurably slow. Even then, fix the data structures rather than look for little 5% tweaks.

CVS

We'll probably use CVS, more as a lame distributed file system than as a source code control system. Check-in messages should be a brief summary of what is changing, not an essay. If the code needs comments, put them in the source files (but see above).

Critique

I may suggest lots of changes to your code, many small, some large. Don't lose heart. That usually means that the code is already good and I want to make it even better: you can't polish a turd.

Communication

Don't be a stranger. Keep me up-to-date on your status via email and stop by and chat once in a while.