Christopher Seiwald of Perforce has a whitepaper that talks about the Seven Pillars of Pretty Code.
- 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.
- Keep columns narrow.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.
- Break code into logical 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.
- Set off code blocks with whitespace and comments that describe each block.Comments should rephrase what happens in the block, not be a literal translation into English.
- Reduce, reduce, reduce. Remove anything that will distract the reader.The tighter the scope, the shorter the name.
- 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. These similar looking pieces of code should be lined up one after the other.
- 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. 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.
- Blending. Very good point, quite often people will jump in with whatever style they are comfortable with. It's always a good idea if you can have (smart) coding guidelines (at least at the team level).
- Narrow. I'm *horrible* at this. And when I look at the example code I remember why. I'm used to working on 21" monitors where you might as well use up all your horizontal space so that you can get more vertical space on the screen.
- Logical blocks. Common coding guideline. A function shouldn't span more than one screen.
- Meaningful comments. Common coding guideline.
- Variable length. Common coding guideline.
- Repetition. Interesting, I think too often I'll try to wrap the repetitious code into a general function that does both tasks because I hate when you have to make a change in code to multiple places.
- Nesting. Common coding guideline, reduce nesting as much as possible.
What CodingHorror had to say about it:
It's an entirely reasonable set of advice. Until you realize that Christopher is using his very own jam/make.c as a shining example of the pillars of pretty code.
And make.c is extremely ugly to me.
Besides the fact that it's C, I have a few other problems with Mr. Seiwald's make.c code:
- It embeds source control information in the comments. Isn't this why we have source control systems?
- It uses complex, difficult to maintain block alignments in the comments, variables, and function declarations. Unless your IDE does this for you, this is the formatting equivalent of a house of cards.
- There are functions named make and make0. Ouch.
The code formatting, as promised, is pretty. But the emphasis on formatting does make me wonder– rather than focusing on the external, cosmetic attributes of the code, shouldn't we be searching for something prettier on the inside?
Such as a higher level language?
And it's true. Why not just throw the code into a beautifier like Artistic Style if you just want to "make it pretty"? I also think that (especially with C code) a code documentation tool like doxygen should be used so that the user docs are inline to the code in a standard format.
>> Seven Pillars of Pretty Code
>> Coding Horror: Pretty Code, Ugly Code