Best practices for code formatting on large projects

Question

I maintain the build for a large Java EE/Maven/Hudson/Perforce project with about 20 developers spread across the world.

The solution in-place for code formatting is to format the codebase using Jalopy when the developer runs the build, thereby ensuring any code which has not been formatted gets formatted prior to check-in.

The main problem with this solution, is that if the developer doesn't run a full Maven build before checking in (say they run the unit tests from Eclipse) their code won't get formatted. Then, the next developer who edit the file may have many, many diffs in unrelated sections of the code after they run the formatter.

What source formatting strategy has worked best for you on large projects? Another option I had considered is formatting nightly using an automated process.

Solution 1

The Maven build should just be reporting formatting errors using something like Checkstyle and not automatically formatting the code. That's what your description seemed to imply. This way errors are reported to the developer/Hudson at build time and they can be resolved as needed.

I'd also suggest using a tool like Sonar to keep a history of formatting errors over time (see their time machine functionality).

Solution 2

In order to get consistent formatting to your projects you need to configure the tools to do it automatically. I would suggest the following:

Eclipse Formatter

For Eclipse there is an option in Preferences (Java->Code Style->Formatter) where you can configure how you want your projects to be formatted. Create a new profile and put your configuration there.

Once you finish, there is an export function (it is well hidden, click on Edit and then Export). Pass the configuration to the rest of the team so that the can import it.

Eclipse Save Actions

Still having the formatter configured does not guaranty you that the developers will format the code before committing so you need to configure automatic format.

Go to the Preferences again (Java->Editor->Save Actions) and select Format Source Code. This way the code is formatted while saving the file.

Eclipse Checkstyle Plugin

Some developers may forget to do these steps correctly, so you need a way to locate that.

Install the Checkstyle plugin for Eclipse:

• Goto Help->Install Software...
• Add http://eclipse-cs.sf.net/update/
• Install latest checkstyle plugin

Once you install the plugin, you can create a configuration for it. The configuration can then be exported for the rest of the team, or even better uploaded to a server and reference to the configuration remotely.

The advantage of having a remote configuration is that you can also reference to it by the maven-checkstyle-plugin and it can give you reports by launching it on a CI server.

If you want to be hard-core you can set the basic configuration (the ones done automatically by the formatter) to errors instead of warnings so that the developer with a misconfigured eclipse sees the error before commiting.

Pre-configured Eclipse

If you want to go to the next level, you create a pre-configured eclipse, and distribute that version to your developers so that they don't need to do anything.

Side-effect bonus: you keep out the version inconsistencies on the development platform. Configuration Management is not about only to the source code, but the development tools also. Keeps things more predictable.

Solution 3

One way to handle this would be to format the code in a pre-commit hook with something like Jalopy or JIndent or even Eclipse built-in code formatter (that you can invoke from the command line). AFAIK, this is the only way to ensure that versioned code is always properly formated if you can not enforce people to run an automated build before commiting. But I don't know if Perforce does support pre-commit hooks.

If it doesn't, another option would be to use the Jalopy Maven Plugin or the Maven Checkstyle Plugin at build time and make the build fail when a rule is broken (and have the CI engine report it). Build failures for cosmetic things can be pretty annoying though.

So, indeed, running a nightly process to format the code might be an alternative. In that case, the Jalopy Maven Plugin or the other mentioned tools may help you, it will actually depend if you want to use Maven or not for this job.

Solution 4

If all (or most) of your developers are using Eclipse, you can export the formatting rules and save actions to your team's liking and have everyone share the same preferences.

Solution 5

The best solution I've seen for this is the approach taken by CXF, described in detail in Connecting Maven, Eclipse, Checkstyle, and PMD.

They integrate checkstyle with Eclipse, using the Eclipse-cs plugin Dimitris mentioned in another reply. This allows Eclipse to generate errors if their code breaks any code formatting rules. They also integrate checkstyle with Maven, so that the verify step will fail if their code does not adhere to the checkstyle rules. They also have a redundant set of auto-formatting rules defined within Eclipse, which makes it easy to quickly format code which will pass checkstyle's standards.

This implies a lot of configuration for Eclipse. They automate this step by putting together a collection of Maven plugins which will generate a CXF-specific workspace, which includes the necessary checkstyle/autoformatting configuration.

View more solutions