Formal Standards

Formal Standards

Problem: When reading code written by other programmers, it is sometimes hard to understand due to the formatting style used by that author.

Context/Forces: Solution: Develop and adopt formal style standards. Enforce the standards during CodeReviews and DesignReviews.

Have a separate review for CodingStandards so that code reviews don't degrade into trivial nitpicking about style instead of content. The code standards must be accepted by all beforehand.

Resulting Context: All code and designs will be more easily understood by all developers in the group. Bugs due to typos will be fewer.

Related Patterns: See CodeReviewPatterns.

I've seen some groups let programmers use whatever the heck programming style they want, but an auto-formatting/pretty-printing program formats the code for inspection (and/or before it is checked-in). Doesn't that eliminate the need for some of these things? Which ones can't be fixed by this method? Aren't those more important?

1. If a coding standard is just about where to set the parentheses this will be good enough. Even so, a programmer might have problems to understand his own code after re-formatting.

2. However I believe a good coding standard should also include some other things: how to name different types of variables (local, global), constants, functions and certain design principles (especially in object-oriented environments). This cannot be done automatically, and if it could it would certainly confuse any programmer.

The programmer unable to escape his own style is the same one who repeats a beginner's mistakes. A good programmer is like good software -- able to quickly adapt to his environment. Using a tool to munge another's code into a personal mindset only calcifies that mindset, making the programmer resistant to change.

Naming conventions are probably more important than formatting. Class names, instance variable names, method names, temp names. Naming things the same lets you find what you're looking for easily, lets your fingers type things more reliably, lets you guess more accurately what to do.

Use of standard refactoring practices makes all the code have the same kind of shape, making it easier to understand and easier to change.

A programmer who uses whatever the heck style he prefers is far less likely to be doing careful work than one who knows and follows the standards. He is far more likely to be unsocialized in other important ways, such as testing. He clearly values individuality more than he values communication.

Code which is written in individual style is far harder to understand and modify by others. This leads to slow going when browsing, and to undesirable forms of CodeOwnership.

These are all more important than indenting. --RonJeffries

If layout and style are important (which, of course, they are) shouldn't they be implemented and tested automatically by something like VisualAgeSmalltalk's QA Tools? Some of the style tests are quite sophisticated. You could argue that this is a sort of meta-unit test: no code ships until it's passed...

I find when I am refactoring that much of my work involves renaming things. Does that match C3's experience? Of course, recently I have been taking someone else's monolithic code and reworking it. -- MichaelFeathers

Yes, when done well, a good chunk of refactoring is replacing bad or outdated names (concepts) with better more current ones. There's more, of course, but a surprising amount of renaming. --rj

See SystemOfNames

I think the issue being skirted is what needs to be contained in coding standards.

If I have to sit through another discussion of (take your pick): brace placement, TABs versus spaces for indentation, exiting loops with embedded returns versus single return, camel case versus underscores, I'll barf. I have never found any of these issues hindered nor help readability, nor found them to be a source of bugs. A coding standard, however, that gave guidelines on how and when to partition code into methods, partition methods into classes, partition classes into components, etc. would be of benefit. -- WayneMack

A team that programs together will quickly arrive at standards that are situationally appropriate and easy to follow. When they do so they are relying on an innate linguistic skill that automatic formatters have yet to duplicate. -- WardCunningham

CategoryPattern CategoryCodingIssues

View edit of November 23, 2014 or FindPage with title or text search