编码约定

多年来，PDFBox项目已经采用了许多编码约定。旧代码中并不总是遵循这些规则，但新代码应尽可能遵循这些规则。

格式

  • 牙套有自己的路线。

  • 始终将大括号与控制流语句一起使用。

  • 行长度不超过 100 个字符，包括 JavaDoc。

  • 换行应使用 4 或 8 个字符的缩进，或与前一行上相同级别的表达式对齐。

  • 换行应在运算符之后断开，而不是在运算符之前断开。

  • 首选对齐的换行。

  • 首选对齐的包装参数列表。

空白

  • 四个缩进空格，无制表符。

  • 不要在括号周围使用空格。

  • 在控制流关键字后使用空格。

  • 最好使用空行来分隔逻辑代码块，但不要过多。

  • 不喜欢跟随带有空格的强制转换。

结构

  • 不要使用包导入（例如import java.util.*)

  • 静态字段和方法必须出现在类的顶部，在任何其他代码之前。

  • 在类中，定义应按如下顺序排序：

    类（静态）变量 实例变量

    构造函数
    方法

JavaDoc

  • 公共和受保护的方法和字段必须具有 JavaDoc。

  • 不要使用标签。@version

  • 不要使用标签。@since

  • 不要在标记中包含您的电子邮件地址。@author

  • 您可以省略 getter 的标签，只要您包含以“返回”一词开头的摘要即可。@return

  • 私有方法不需要JavaDoc，但如果它添加了有价值的信息，则可能有部分JavaDoc。

评论

  • 只在代码中使用行注释，切勿阻止注释。

  • 更喜欢在自己的行上添加注释，而不是尾随注释，除非后者更具可读性。

  • 用空格作为前缀行注释。// like this

变量

  • 更喜欢在使用变量时初始化变量，而不是在使用前进行 C 样式声明。

  • 尽可能使用最终字段。

控制流

  • 首选多个返回语句而不是其他控制流逻辑。

  • 首选 switch 语句而不是多子句 if-then 语句。

接口设计

  • 为变量和方法指定有意义的名称。保持简短，但不要使用缩写。首选使用与 PDF 规范相同的术语。

  • 对于非最终公共类，首选最终类和最终保护方法，这会减少公共 API 的外围应用。

  • 避免在公共类中使用非最终受保护的变量。当公共类中需要受保护的字段时，首选受保护的 getter 而不是受保护的变量。

  • 最小化 API。不要仅仅因为可以就公开一切。

  • 除非有明确的需要，否则不要公开实现细节：允许子类化意味着受保护方法的行为成为公共 AP 协定的一部分。

  • 避免不必要的抽象。虽然我们鼓励您避免脆弱的设计，但为“未来使用”而设计的 API 将具有正确的 API，而没有任何实际使用它的代码，这是不明智的。

例

Here's an example of PDFBox's formatting style:

public class Foo extends Bar
{
    public static void main(String args[])
    {
        try
        {
            for (int i = 0; i < args.length; i++)
            {
                System.out.println(Integer.parseInt(args[i]));
            }
        }
        catch (NumberFormatException e)
        {
            e.printStackTrace();
        }
    }
}

Eclipse Formatter

Eclipse users may download this preferences file: and import this into Eclipse. (Window->Preferences, go to Java->Code Style->Formatter and click "Import..."). Once you have done this you can reformat your code by using Source->Format ().pdfbox-eclipse-formatter.xmlCtrl+Shift+F

Also note that Eclipse will automatically format your import statements appropriately when you invoke Source -> Organize Imports ().Ctrl+Shift+O

IntelliJ IDEA users may leverage the same format preferences by importing them into Adapter for Eclipse Code Formatter plugin. To make the code conform to the format rules, run Code -> Reformat Code command () and/or make sure to set the same named flag in Commit dialog.Ctrl+Alt+L