Wed, 31 Jan 2007

I've come to believe that having a coding style is important, but
enforcement is not. If programmers on my team can't adhere a style without
having to have their wrists slapped by some tool or enforcement police,
it's likely there are more serious issues lurking that will bite the
team far worse than misplaced curly braces or indentation errors.

There is one kind of problem in the realm of keeping up a good,
consistent coding style that I see regularly. In the case were the
team uses and idea or other automated code reformatting that generates
confusing and useless diffs in the version control system have a fairly
simple, non-technical, solution.

It works like this: When you are preparing to edit a source file to make
some semantically important changes and the automated code-reformatter
also wants to move things around, do the change in two steps. Step one:
let the reformatter do its cleanup, make everything pretty, but make NO
other changes. Check in the file with a comment like "Reformat changes
only" to indicate that the code hasn't really changed*. NOW make your
real changes as needed, run your unit tests, etc, and check in with the
actual change message.

Result: The diffs between what you changed and the original source
are clear and isolated, yet there is a record in the changelog of the
reformatting, which can be compared to the prior version (if needed)
to see what the formatter did.

The extra effort is minimal for programmers who are serious about
enforcing a coding style, while the benefits of being able to
differentiate real changes from reformatting (and potentially help in
identifying programmers who are checking in code that doesn't meet the
style guidelines) are manifold.

* Note that sometimes reformatting code, even though there are supposedly
no changes, will in fact result in changed behavior, especially in
languages like Python where whitespace is meaningful, but even in
languages where whitespace is mostly ignored. Another reason it's good
to have a clear record in the source control of only formatting change
check-ins.