java 大型项目代码格式化的最佳实践

Best practices for code formatting on large projects

提问by SamBeran

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

我维护一个大型Java EE/ Maven/ Hudson/ Perforce项目的构建，该项目有大约 20 名开发人员分布在世界各地。

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

代码格式化的就地解决方案是在开发人员运行构建时使用Jalopy格式化代码库，从而确保任何未格式化的代码在签入之前被格式化。

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.

这个解决方案的主要问题是，如果开发人员在签入之前没有运行完整的 Maven 构建（假设他们从Eclipse运行单元测试），他们的代码将不会被格式化。然后，下一个编辑文件的开发人员在运行格式化程序后可能在代码的不相关部分有很多很多差异。

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

在大型项目中，哪种源格式策略最适合您？我考虑过的另一个选择是使用自动化过程每晚格式化。

回答by Taylor Leese

The Maven build should just be reporting formatting errors using something like Checkstyleand 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.

Maven 构建应该只是使用Checkstyle 之类的东西报告格式错误，而不是自动格式化代码。这就是你的描述似乎意味着什么。这样错误会在构建时报告给开发人员/Hudson，并且可以根据需要解决。

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

我还建议使用像Sonar这样的工具来保留一段时间内格式错误的历史记录（请参阅它们的时间机器功能）。

回答by Dimitris

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

Eclipse 格式化程序

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.

对于 Eclipse，在 Preferences (Java->Code Style->Formatter) 中有一个选项，您可以在其中配置您希望如何格式化项目。创建一个新的配置文件并将您的配置放在那里。

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

Eclipse 保存操作

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.

再次转到 Preferences（Java->Editor->Save Actions）并选择 Format Source Code。这样，代码在保存文件时被格式化。

Eclipse Checkstyle Plugin

Eclipse Checkstyle 插件

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

一些开发人员可能会忘记正确执行这些步骤，因此您需要一种方法来定位这些步骤。

Install the Checkstyle plugin for Eclipse:

为 Eclipse 安装 Checkstyle 插件：

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

• 转到帮助-> 安装软件...
• 添加http://eclipse-cs.sf.net/update/
• 安装最新的 checkstyle 插件

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.

拥有远程配置的优点是您还可以通过 maven-checkstyle-plugin 引用它，并且它可以通过在 CI 服务器上启动它来为您提供报告。

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.

如果您想成为硬核，您可以将基本配置（由格式化程序自动完成的配置）设置为错误而不是警告，以便具有错误配置的 eclipse 的开发人员在提交之前看到错误。

Pre-configured Eclipse

预配置的 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.

如果您想进入下一个级别，您可以创建一个预配置的 Eclipse，然后将该版本分发给您的开发人员，这样他们就无需执行任何操作。

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.

副作用奖励：您将开发平台上的版本不一致排除在外。配置管理不仅涉及源代码，还涉及开发工具。使事情更可预测。

回答by Pascal Thivent

One way to handle this would be to format the code in a pre-commit hook with something like Jalopyor JIndentor 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 alwaysproperly 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.

处理此问题的一种方法是使用Jalopy或JIndent甚至 Eclipse 内置代码格式化程序（您可以从命令行调用）之类的东西在预提交挂钩中格式化代码。AFAIK，如果您不能强制人们在提交之前运行自动构建，这是确保版本化代码始终格式正确的唯一方法。但我不知道 Perforce 是否支持预提交钩子。

If it doesn't, another option would be to use the Jalopy Maven Pluginor the Maven Checkstyle Pluginat 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.

如果没有，另一种选择是在构建时使用Jalopy Maven 插件或Maven Checkstyle 插件，并在规则被破坏时使构建失败（并让 CI 引擎报告它）。但是，化妆品的构建失败可能非常烦人。

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

因此，实际上，每晚运行一个进程来格式化代码可能是另一种选择。在这种情况下，Jalopy Maven Plugin或其他提到的工具可能会帮助你，这实际上取决于你是否想使用 Maven 来完成这项工作。

回答by piepera

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

我见过的最好的解决方案是CXF采取的方法，在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.

他们使用另一个回复中提到的 Eclipse-cs 插件 Dimitris将 checkstyle 与Eclipse集成。这允许 Eclipse 在其代码违反任何代码格式规则时生成错误。他们还将 checkstyle 与Maven集成，因此如果他们的代码不遵守 checkstyle 规则，验证步骤将失败。它们还有一组在 Eclipse 中定义的冗余自动格式化规则，这使得快速格式化将通过 checkstyle 标准的代码变得容易。

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.

这意味着 Eclipse 需要进行大量配置。他们通过将一组 Maven 插件放在一起来自动执行此步骤，这些插件将生成特定于 CXF 的工作区，其中包括必要的检查样式/自动格式化配置。

回答by matt b

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.

如果您的所有（或大多数）开发人员都在使用 Eclipse，您可以导出格式规则并根据团队的喜好保存操作，并让每个人共享相同的首选项。

回答by Preet Sangha

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.

你能在 Perforce 中设置一个签入规则来格式化签入时的代码吗？我没有使用过 perforce，所以我无法发表评论 - 但当我们在我们的团队中讨论代码格式化强制选项时，我们认为这是合适的。

回答by Kevin Conner

This may not help much, but the Go language source treeautomatically 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.

这可能没有多大帮助，但是Go 语言源代码树会使用他们设置的命令行应用程序自动格式化您推送到其中的内容。它是在 Mercurial 中完成的，而不是 Perforce。但是，也许您可​​以看到他们是如何做到的。详细信息必须在golang.org 的某个地方。

回答by Thorbj?rn Ravn Andersen

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.

如果正确的格式对您来说很重要，那么配置 Perforce 在签入时执行自己的格式设置，并告诉它如果源文件的格式版本与提交的版本不同，则拒绝提交。

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

就个人而言，我们只使用 Eclipse 保存操作，并在保存时告诉它重新格式化。对我们来说已经足够好了。