Java Reference
In-Depth Information
9.7
Building a good style guide
Now that we've seen a good set of conventions, it's time to discuss ways to
put them together into a style guide. A style guide exists to serve the pro-
gramming community and the customer. It is intended to assist with the
production of quality code. To accomplish that objective, it must be read and
embraced by the entire organization. I believe in very short style guides for
that reason. Here are some tips to consider:
Keep style guides short.
Everyone who touches code should read the style guide.
Maintain the style guide like an application: fix it when it is broken.
Use it and embrace it, but do not be overly rigid. Understand when
exceptions apply.
Make it appropriate to the toolsets and skill levels on the team.
Did I mention
short
? Nothing is more frustrating than a code cop screaming
about section 145.265.23 of a style guide at 5:30 on a Friday afternoon. Long
guides have the potential to turn into either unused boat anchors or crusading
holy books. Instead, a style guide should take into account the tools, personal-
ities, and skills of an organization. A style guide for a team of longhaired, 10-
year Jolt-drinking veterans wouldn't need to preach about basic object-ori-
ented design. A style guide for a team using an integrated development envi-
ronment probably wouldn't need to mention make-file structure, because the
development environment manages that.
9.7.1
Buy, borrow, or steal?
Many consultants sell programming style guides for a living. Some additional
style guides are available in books or for free on the Internet. Which approach
is best? Should you have a consultant build one? Should you combine from
different sources? Should you build one from scratch? I've coded on teams
that approached programming style in different ways. One team chose not to
use a style guide; we failed. The successful teams used these methods:
Build it from scratch.
This is the approach that was taken at Contextual,
Inc. (see the next section). Because the team was small and communica-
tion was good, this approach worked well.
Adapt a style guide from another assignment.
This is by far the most
common approach. Most good programmers know what they like. A
