Maven – Maven 代码风格和代码约定

Maven 代码风格和代码约定

本文档描述了开发人员和贡献者应如何格式化代码以提高一致性、可读性和可维护性。

通用代码样式和约定

所有工作文件（java、xml 等）都应遵守以下约定：

License Header ：始终在签入源代码存储库的所有文件中添加当前ASF 许可证头。
尾随空格：删除所有尾随空格。如果您使用 Eclipse，则可以使用Anyedit Eclipse 插件。

和以下风格：

缩进：永远不要使用制表符！
换行：始终使用 120 列的线宽。

注意：下一节中列出的特定样式和约定可以覆盖这些通用规则。

爪哇

Java 代码风格

Java的Maven风格主要是：

空格：控制语句之后和参数之间的一个空格（例如，if ( foo )代替if(foo)），myFunc( foo, bar, baz )而不是myFunc(foo,bar,baz)）。方法名称后没有空格（即void myMethod(), myMethod( "foo" )）
缩进：始终使用 4 个空格缩进，从不使用制表符！
块：总是用新的大括号括起来。
换行：Java 代码和 Javadoc 始终使用 120 列的行宽。

阅读性：如果需要，指定代码分组成员。例如，在 Mojo 类中，您可以：

public class MyMojo
{
    // ----------------------------------------------------------------------
    // Mojo components
    // ----------------------------------------------------------------------

    /**
     * Artifact factory.
     *
     * @component
     */
    private ArtifactFactory artifactFactory;

    ...

    // ----------------------------------------------------------------------
    // Mojo parameters
    // ----------------------------------------------------------------------

    /**
     * The POM.
     *
     * @parameter expression="${project}"
     * @required
     */
    private MavenProject project;

    ...

    // ----------------------------------------------------------------------
    // Mojo options
    // ----------------------------------------------------------------------
    ...

    // ----------------------------------------------------------------------
    // Public methods
    // ----------------------------------------------------------------------

    /**
     * {@inheritDoc}
     */
    public void execute()
        throws MojoExecutionException
    {
      ...
    }

    // ----------------------------------------------------------------------
    // Protected methods
    // ----------------------------------------------------------------------
    ...

    // ----------------------------------------------------------------------
    // Private methods
    // ----------------------------------------------------------------------
    ...

    // ----------------------------------------------------------------------
    // Static methods
    // ----------------------------------------------------------------------
    ...
}

以下部分展示了如何在 IDEA 和 Eclipse 中为 Maven 设置代码样式。强烈建议补丁在应用之前使用此样式。

IntelliJ IDEA

使用 File > Settings > Editor > Code Style > Gear icon > Import Scheme > IntelliJ IDEA Code Style XML 将其下载maven-idea-codestyle.xml并导入 IDEA

蚀

下载maven-eclipse-codestyle.xml.

在此之后，选择 Window > Preferences，然后打开 Java > Code Style > Code Formatter 的配置。单击标有 Import... 的按钮并选择您下载的文件。为样式命名，然后单击“确定”。

为了确保包导入顺序与下面描述的布局一致，请下载maven-eclipse.importorder，选择 Window > Preferences 并导航到 Java > Code Style > Organize Imports。单击导入...并选择下载的文件以更改导入顺序。

Java 代码约定

出于一致性原因，我们的 Java 代码约定主要是：

命名：常量（即静态最终成员）应始终为大写。为类和方法使用简短的描述性名称。
组织：避免使用公共内部类。更喜欢接口而不是默认实现。
修饰符：避免在所有字段和参数上使用 final 修饰符。更喜欢使用私有或受保护字段而不是公共字段。
异常：抛出有意义的异常以使调试和测试更容易。
文档：很好地记录公共接口，即所有重要的公共和受保护函数都应该包含指示它们做什么的Javadoc。
测试：所有重要的公共类都应该有相应的单元或集成测试。

Java 代码约定 - 导入布局

出于一致性原因，Java 导入应组织为：

导入javax.*
空行
导入java.*
空行
进口所有其他进口
空行
导入静态所有其他导入

每组中的所有进口都应按字母顺序排序。

缩进：总是使用 2 个空格缩进，除非你包装一个新的 XML 标记行，在这种情况下你应该缩进 4 个空格。

换行符：对于复杂的 XML 类型，总是使用带有缩进的新行，对于简单的 XML 类型，不要换行。始终使用新行来分隔 XML 部分或块，例如：

<aTag>
  <simpleType>This is a simple type</simpleType>

  <complexType>
    <simpleType>This is a complex type</simpleType>
  </complexType>
</aTag>

在某些情况下，添加注释可以提高块的可读性，例如：

    <!-- Simple XML documentation                                               -->

要么

    <!-- ====================================================================== -->
    <!-- Block documentation                                                    -->
    <!-- ====================================================================== -->

通用 XML 代码约定

XML 文件尚不存在通用代码约定。

POM 代码约定

该团队在 2008 年 6 月结束时投票决定遵循特定的 POM 约定来订购 POM 元素。这次投票的结果是Maven 项目描述符不再被视为排序的参考。

以下是所有 Maven POM 文件的推荐顺序：

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion/>

  <parent/>

  <groupId/>
  <artifactId/>
  <version/>
  <packaging/>

  <name/>
  <description/>
  <url/>
  <inceptionYear/>
  <organization/>
  <licenses/>

  <developers/>
  <contributors/>

  <mailingLists/>

  <prerequisites/>

  <modules/>

  <scm/>
  <issueManagement/>
  <ciManagement/>
  <distributionManagement/>

  <properties/>

  <dependencyManagement/>
  <dependencies/>

  <repositories/>
  <pluginRepositories/>

  <build/>

  <reporting/>

  <profiles/>
</project>

评论：

<project/> 元素总是在一行。
这些块是自愿用一条新线分隔的，以提高可读性。
<dependencies/> 和 <dependencyManagement/> 标签中的依赖关系没有特定的顺序。开发人员可以自由选择排序，但按主题（如 groupId ie org.apache.maven）对依赖项进行分组是一种很好的做法。

注意：有两种方法可以改变 pom 文件的顺序，Tidy Maven 插件或Sortpom Maven 插件。

XDOC 代码约定

出于一致性和可读性的原因，XDOC 文件应遵守：

元数据：始终在 <properties/> 标记中指定元数据。
Sections：对于 <section/> 标签，总是使用带有缩进的新行。

FML 代码约定

出于可读性原因，FML 文件应遵守：

常见问题解答：始终为 <faq/> 标签使用带有缩进的新行。