Technical_Docs/Coding_Standards_Document_CPP/google-java-styleguide/source_file_structure.rst

.. _source-file-structure:

3. 源文件结构
----------------

源文件应由以下部分 **按顺序** 组成：

- 1. 许可或版权信息（如果有的话）
- 2. 包的声明
- 3. 导入语句 （Import statements）
- 4. 有且仅有一个顶级类

每个部分之间用 **一个** 空白行隔开。

3.1. 许可或版权信息（如果有的话）
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

如果文件中应包含许可证或版权信息，那么它应被放在此处。

.. _package-statement:

3.2. 包声明
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

包声明 **不换行**。列限制（4.4节，:ref:`Column limit: 100 <column-limit>`）不适用于包声明。

.. _import-statements:

3.3. 导入语句 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

3.3.1. 不使用通配符导入
""""""""""""""""""""""""""""""""""""""""""""""""""

**不使用** 任何形式的 **通配符导入** ，无论是静态的还是其他形式。

3.3.2. 不换行
""""""""""""""""""""""""""""""""""""""""""""""""""

导入语句 **不换行** 。列限制（4.4节， :ref:`Column limit: 100 <column-limit>` ）不适用于导入语句。

3.3.3. 排序和间距
""""""""""""""""""""""""""""""""""""""""""""""""""

按以下顺序导入：

- 所有的静态导入都在一个单独的块中。

- 所有非静态导入都在一个单独的块中。

如果既有静态导入又有非静态导入，则两个块之间有一个空白行。导入语句之间没有其他空白行。

在每个块中，导入的名称按ASCII排序顺序出现。（ **注意** ：这不等同于按整个导入语句的ASCII排序，因为'.'排在';'之前。）
（译者注：这种情况只会出现在包名结尾为'.'时，所以实际上可以忽略不计。例如： ``import packageA.ClassA; import packageA.ClassA.;`` ，如果按整个语句的ASCII排序，后句应排在前句之前，因为'.'在ASCII中排在';'前。除此之外其他情况按包名排序和按整个语句排序应得到相同的结果）

3.3.4. 不对类使用静态导入
""""""""""""""""""""""""""""""""""""""""""""""""""

不使用静态导入来导入静态嵌套类，而是使用常规导入。

3.4. 类的声明
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. _one-top-level:

3.4.1. 有且仅有一个顶级类声明
""""""""""""""""""""""""""""""""""""""""""""""""""

每个顶级类都位于其自己的源文件中。

3.4.2. 类中内容的顺序
""""""""""""""""""""""""""""""""""""""""""""""""""

类中成员和初始化器的顺序对于代码的可读性有很大影响。然而，并没有一个唯一正确的顺序，不同的类可能会以不同的方式排列其内容。

重要的是，每个类都使用 **某种逻辑顺序** ，并且在被问及时，其维护者可以做出相应的解释。例如，新方法不仅仅是习惯性地添加到类的末尾，因为那会导致内容是“按添加时间排序”的，这并不是一个有逻辑的排序方式。

3.4.2.1. 重载：永不分割
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

类中拥有同一名称的方法应出现在一个连续的组中，中间不应该有任何其他成员。对于多个构造函数（它们的名称总是相同的）也是如此。即使在方法之间的修饰符（如 ``static`` 或 ``private`` ）不同时，此规则仍然适用。