Resume for Steven E. Newton
Readings for Code Janitors
Steven E. Newton
Crater Moon Development
Is Coding Style Important?
Over at Artima, Frank Sommers writes How Important is Coding Style, and How Do You Enforce It?
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 changed1. 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. ↩︎