Best Practices for Code Formatting on Large Projects

Question

I maintain the build for a large J2EE/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.

There main problem with this solution, is that if the developer doesn't run 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.

Answer 1

Can you set a checkin rule in Perforce to format the code on checkin? I've not used perforce so I cannot comment - but this is the kind of thing we thought would be appropriate when we discussed code formatting enforcement options in our team.

Answer 2

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).

Answer 3

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.

Answer 4

This may not help much, but the Go language source tree automatically formats what you push into it, using a command line app that they've set up. It's done in Mercurial, not Perforce. But, maybe you can see how they did it. Details must be somewhere in golang.org.

Answer 5

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.

Answer 6

If proper formatting is essential to you, then configure Perforce to do its own formatting run on checkin, and tell it to refuse the commit if the formatted version of the source file is different from the one submitted.

Personally we just use Eclipse Save Actions, and tell it to reformat when saving. Good enough for us.

Answer 7

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.