Seven Pillars of Pretty Code

Introduction

The essence of pretty code is that one can infer much about the code's structure from a glance, without completely reading it. I call this "visual parsing": discerning the flow and relative importance of code from its shape. Engineering such code requires a certain amount of artifice to transform otherwise working code into working, readable code, making the extra step to leave visual cues for the user, not the compiler.

These Pillars of Pretty Code are somewhat intertwined. The first five are formulaic; the last two require intuition. Just about all of them are evidenced in jam/make.c. This is a C example, but these practices can be applied to just about any high level programming language.

Blend In

Code changes should blend in with the original style. It should not be possible to discern previous changes to a file without seeing the previous revisions. Nothing obscures the essential visual cues more than a shift in style.

This practice should be applied as wide as possible: absolutely within functions, generally within a file, and if you're lucky across the system.

When presented with really ugly or neglected code, and you can't infer anything about its structure from a glance, you may have to consider reformatting it wholesale. The deep understanding you gain will then be available for all subsequent readers.

make.c is on revision 44, with no major rewrites.

Bookish

Keep columns narrow. Just as with books and magazines, code should be narrow to focus the gaze. As I mention in "Overcome Indentation," the left edge of the code holds the structure and the right side holds the detail, and big long lines mix zones of structure and detail, confusing the reader.

There are many remedies for long lines: use shorter names (see "Declutter"); line up multiple function arguments one per line (see "Make Alike Look Alike"); and just plain streamline logic (see "Overcoming Indentation").

As a rule of thumb, 80 columns fits everywhere, though admittedly it is not physically possible to format some code (such as wide tables) within this strict limit.

make.c uses both short variable names and a strong hand on indentation to keep itself narrow.

You might also like...

Comments

 Perforce Founded in 1995, Perforce Software Inc. develops, markets, and supports Perforce, the Fast Software Configuration Management System. Perforce Software is headquartered in Alameda, Calif., and sells...

Contribute

Why not write for us? Or you could submit an event or a user group in your area. Alternatively just tell us what you think!

Our tools

We've got automatic conversion tools to convert C# to VB.NET, VB.NET to C#. Also you can compress javascript and compress css and generate sql connection strings.

“There's no test like production” - Anon