Summary
Recent years have witnessed the emergence of many high-quality tools that help enforce a consistent coding style. But how effective are these tools in practice, and how do they fit into your process of enforcing consistency in your source code?
Advertisement
In his essay on Self-Reliance, Emerson famously noted that:
A foolish consistency is the hobgoblin of little minds, adored by little statesmen and philosophers and divines. With consistency a great soul has simply nothing to do. He may as well concern himself with his shadow on the wall. Speak what you think now in hard words, and to-morrow speak what to-morrow thinks in hard words again, though it contradict every thing you said to-day.
It may be so, but few things can irk a good developer as deeply as encountering code that's inconsistent in its coding style. Most projects, indeed, define coding standards, and the Java language itself has an officially blessed style guide. For those who dream in code, especially, poor coding style means nightmare.
Some developers may argue that automated tools make it less important for developers to focus on following any particular coding style. IDEs, for instance, allow project-wide code style settings, and can even reformat code to adhere to a particular standard. Other tools, such as CheckStyle—which today released its new 4.3 version— can flag potential style problems in an existing code base.
While IDEs and style checking tools do an overall excellent job helping developers adhere to coding standards, I find especially IDE-based auto-reformatting less than practical: When auto-reformatting entire classes, the newly-formatted source files cause the source control system to indicate lots of code changes, even though those changes were only in formatting. The newly formatted version is really the same version as the previous one, unless we consider code reformatting a form of refactoring. Otherwise, ensuring consistency in coding style forces us to forfeit consistency in versioning (having a new version number indicate a changed source file).
In practice, I think that auto-reformatting code once in a while may be fine, but can cause confusion if used more often, especially on a package and project level. As a result, the automated tools notwithstanding, developers still need to carefully follow a project's coding style.
But what if they don't? I have certainly seen code written by fairly well-known developers that wouldn't pass a strict code-style check. In other words, excellent code, but with somewhat inconsistent style. At Artima, we have already integrated CheckStyle into our build process as a task we can run at our leisure to find style inconsistencies. But a clean bill of code style health is not currently a requirement for checking in code. We are thinking of a deeper integration, and I wonder to what extent others have required style checking as a condition of allowing commits, for instance.
I realize that part of this question relates to just how deeply we define code style. For there is a spectrum ranging from naming conventions, block coding style, and tolerance of code duplication, to the order of import statements and the treatment of white spaces. While tools can alert us of style violations occurring almost anywhere in that wide range, just how tight do you set the lever before the automatic code style police becomes a hurdle in developers getting their job done? And, more importantly, if you have followed automated style enforcement practices, to what extent did you see a correlation in developer productivity, or in just general developer happiness?
Coding style is critical. Coding style is more than fashion style. It's not merely superficial. Coding style reflects wisdom of programming.
Coding style, unfortunately, cannot be enforced. Best bet, if you are serious about high quality code, is to get people on board who care about clean and elegant code, who don't mind taking 15 minutes to properly name a variable (understanding how it saves months down the road), who code slowly, deliberately, thoughtfully, people who add features while constantly reducing total lines of code, etc. Those are very rare people to find. Those people love what they do.
You cannot take people who couldn't care less about coding style and then simply "enforce" it. That will never, ever work. Think why. Tools can only enforce superficial aspects of style. A person can at best enforce only one other person (people's energies are roughly equal). It's hopeless to have one person try to enforce a whole team if each teammate has equal determination to avoid coding with good style, equal to that of one person who wants to enforce it.
You need people who do the right thing voluntarily. Everyone makes mistakes though. Even the best. But it's one thing to make mistakes in good faith, and it's another thing to willfully ignore something.
So, if you want code of the highest quality, policies and enforcement are merely accessories. They are not how you actually get there.
I have worked on XP teams where there was no official coding style but everyone converged on a style that emerged.
I have worked on a non-xp team where we used a style-checker to gradually ratchet up the rules until we all reached a common style.
What doesn't work is to simply accounce a coding style and expect everyone to adopt it. Too many arguments up front.
The diff in my IDE ignores whitespace so that's not an issue but the order of imports IS important otherwise you get a merge conflict every time someone organizes imports.
The most important thing, if you are using a tool to enforce the standards, is to only choose rules that ALWAYS apply. IDEA's (and Eclipse's) default set does this well - but as soon as you have a rule (like No Unused Params) that only applies some of the time you create a precedent for sometimes ignoring the warnings.
Kevin
www.junitfactory.com You send us code. We send back tests. For free.
Completely unimportant. So long as you haven't done anything outrageous like obfuscated C code, it's gotta be by far the least important aspect of code quality. Well named variables, DRY, clear intentions, adequate javadocs and good design principles are vastly, vastly more important than where the bleeping brackets go.
On one project, it was a bonus that everybody had slightly different styles. If I were perusing code, I could quickly tell who wrote the original code (and therefore, who to ask about it) by the placement of their brackets.
I don't think it is amazingly important these days, modern IDEs and code pretty printers will do the work for you. I use the Jalopy tool which is a plug in for most IDEs. I set up a coding style, which in the case of Jalopy not only includes layout but also copyright notices, naming conventions, etc., that I like and reformat code that I am working on. When the next person takes my code they format it how they like it if they don't like my style. At least in the case of code layout it is so automated and slick that it isn't a problem. In terms of naming conventions etc. the IDE is great for changing names if a code convention is broken.
I think style enforcing is easily taken too far has has been by checkstyle files I've seen in neighboring companies as well as the one I'm at currently.
Enforcing things like a consistent indentation, forcing brackets on a single line if statement is just fine by me as it's maintaining the readability of the code across a project or even across a company. This makes it easier to read code you've never seen before which is a good thing.
I have seen things like explicitly the explicit declaration of a runtime exception in the throws clause of a method signature register a checkstyle warning and this kind of thing I'm very much against. This kind of rule at the very least makes a good programmer document this exception being thrown in a javadoc instead of a clever exception name in the method signature being self explanatory. At the worst it stifles creativity which is infinitely worse.
> I don't think it is amazingly important these days, modern > IDEs and code pretty printers will do the work for you. I > use the Jalopy tool which is a plug in for most IDEs. I > set up a coding style, which in the case of Jalopy not > only includes layout but also copyright notices, naming > conventions, etc., that I like and reformat code that I am > working on. When the next person takes my code they format > it how they like it if they don't like my style. At least > in the case of code layout it is so automated and slick > that it isn't a problem. In terms of naming conventions > etc. the IDE is great for changing names if a code > convention is broken.
I tend to agree ... however I feel that a separate "reformatting" commit is in order so that diffs are decipherable. I've seen 50% of the lines in a file show a change, but only one of them have any semantic meaning, the rest being simple style changes.
> I tend to agree ... however I feel that a separate > "reformatting" commit is in order so that diffs are > decipherable. I've seen 50% of the lines in a file show a > change, but only one of them have any semantic meaning, > the rest being simple style changes.
This is a good suggestion but the formatter I use won't do this *automatically*. It will auto-format on save but not to a different style than the one used for display. You can do it manually though.
Maybe the next generation of IDEs will completely divorce the saving format from the display format and also the diff could work on the AST instead of on the text. The refactoring stuff in modern IDEs is a step in this direction - so we can only hope :)
Coding style is about 2 main things as I see it. It is about understandability or readability aspect. All the effort that goes with consistency, formatting, look and feel for the code falls under this.
The second is more important for the maintainability aspect I guess. How effective is the coding style influencing the design and software quality metrics.
For example a good coding style need to reflect the desirability value of metrics like cohesion, coupling, depth of inheritance tree, encapsulation, complexity versus simplicity, adhering to internationalization standards and perhaps other non-functional attributes (for example the systemic qualities or QOS).
Great developers automatically deliver both aspects.
As for my thoughts, programmers should express their creativity in good code design, not funky new coding styles. Just agree on one of the common coding styles in the language you're using and get past it. Curly bracket wars are the hobgoblins of little minds.
As for enforcement, minor errors should be pointed out to the developer and he will hopefully correct them. Someone that makes egregious digressions from the accepted style is probably not a team player in other ways and you'll probably want to get rid of him, eventually.
In one project we use checkstyle, PMD, and findbugs. I have written unit tests that execute the checkers, and fail if they produce any error. Unfortunately writing these tests requires a bit of trickery, but now it works fine.
We also have a continuous integration server that rebuilds and tests our project, so the build is broken until all style errors are fixed.
This enforcement is quite helpful for the programming style, e.g. you are forced to write simpler code if the class coupling or the code complexity is too high.
In most projects I have worked on, people agreed to a standard and used it. The occasional coding style error was caught by a tool which was used to format the code.
I’m a strong believer in coding standards (of course how these standards are enforced is another important subject) since it increases readability, hence maintainability, significantly.
Previous Topic
