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.*
  • 空行
  • 进口所有其他进口
  • 空行
  • 导入静态所有其他导入

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

JavaDoc 约定

要讨论的

XML

XML 代码样式

XML文件的Maven风格主要是:

  • 缩进:总是使用 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>

评论

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

注意:有两种方法可以改变 pom 文件的顺序,Tidy Maven 插件Sortpom Maven 插件

XDOC 代码约定

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

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

FML 代码约定

出于可读性原因,FML 文件应遵守:

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