Seven Pillars of Pretty Code

Disentangle Code Blocks

Break code into logical blocks within functions, and disentangle the purpose of separate blocks, so that each does a single thing or single kind of thing. A reader can only avoid a total reading if a cursory inspection can reveal the whole block's nature.

One approach is when a function is actually a series of mini-functions: each mini-function is a block, and should be fairly self-contained. That is, information passed from block to block should be carefully considered.

Another approach is when a function is a single large operation. In this case separate blocks could be organized along the lines of type of activity: e.g. initializing variables, checking parameters, computing results, returning results, and printing debug output.

This practice is applied recursively for subblocks within large blocks (like big while loops).

make.c is a hybrid: it separates out a block of debugging/tracing, and is otherwise a series of minifunctions, with each block's purpose segregated.

Comment Code Blocks

Set off code blocks with whitespace and comments that describe each block. Sometimes large blocks (with multiline comments) may embed small blocks (with single line comments).

Comments should rephrase what happens in the block, not be a literal translation into English. That way, even if your code is inscrutable and your comments jibberish, the reader can at least attempt to triangulate on the actual purpose.

Big comments are needed for subtle or problematic code blocks, not necessarily big code blocks.

Historically, I have a ratio of 15% blank and 25% comment lines.

make.c goes so far as the number of the blocks and subblocks for easy identification.

Declutter

Reduce, reduce, reduce. Remove anything that will distract the reader.

Use short names (like i, x) for variables with a short, local scope or ubiquitous names. Use medium length for member names. Use longer names only for global scope (like distant or OS interfaces). Generally: the tighter the scope, the shorter the name. Long, descriptive names may help the first time reader but hinder him every time thereafter.

Eliminate superfluous syntactic sugar (like '!= 0', needless casts, and heavy parenthesizing). Such stuff may help educate a novice programmer, but is unneeded by anyone doing serious debugging and a hindrance to someone trying to get the big (or medium) picture.

Drop 'ifdef notdef' and any other dead code altogether. It's hard enough reading live code. SCM systems hold old code.

make.c uses short names almost exclusively, has just about no syntactic sugar, and has no dead code.