Seven Pillars of Pretty Code

Make Alike Look Alike

Two or more pieces of code that do the same or similar thing should be made to look the same. Nothing speeds the reader along better than seeing a pattern.

Further, these similar looking pieces of code should be lined up one after the other. Such grouping reduces the number of entities the reader has to grasp, a critical approach to simplifying the apparent complexity of code.

This practice is best used in conjunction with "Disentangle Code Blocks:" a separated code block, composed of a pattern of lines with a single purpose, is a simple entity for the reader to grasp.

Unfortunately, this practice must be applied everywhere and requires finesse. Fortunately, it rarely affects the generated code. Examples help:

• Initialize variables together.
• Consistently use 'this' (or don't).
• Line up parameters on a long function call.
• Consistently use {} around if/else clauses: either all blocks have them, or none do.
• Put the { of a if/for/while on its line (because the closing } is).
• Break apart conditionals at the &&'s or ||'s and align them.

make.c's "4d" block is an elaborate example of how many lines of code can be made to look like a single entity.

Overcome Indentation

The left edge of the code defines its structure, while the right side holds the detail. You must fight indentation to safeguard this property. Code which moves too quickly from left to right (and back again) mixes major control flow with minor detail.

Forcibly align the main flow of control down the left side, with one level of indentation for if/while/for/do/switch statements. Use break, continue, return, even 'goto' to coerce the code into left-side alignment. Rearrange conditionals so that the block with the quickest exit comes first, and then return (or break, or continue) so that the other leg can continue at the same indentation level.

Real code of course requires substantial subblocks, necessarily indented, and these subblock will then have their own indentation battles to be fought. You must ensure that you are indenting only to move from structure to detail, and not because of an artifact of the programming language.

This is the most difficult of these practices, as it requires the most artifice and can often influence the implementation of individual functions.

make.c rarely goes more than two levels of indentation, and this is by no means an accident.

Conclusion

These Seven Pillars of Pretty Code aren't the last word, or even the first word, on good code. But for good code they are, I believe, what distinguishes the readable and pretty code from the rest.