某有限公司Java编码规范(doc21页)

1、Java编码规范修订历史记录日期版本说明作者审核人2011-7-110.0.1对 Java 代码风格、注释、命名、 黎建宁声明等规范进行描述2011-8-50.0.2根据征询意见对 Java 编码规范黎建宁、冯彬杰、进行修订张史沛、李思行2011-8-160.0.3对规范中出现模糊定义的地方黎建宁进行细化描述2011-9-130.0.4根据编码的约定情况， 对注释、 黎建宁、李思行声明部分进行了补充2011-9-200.0.5对方法的声明顺序进行补充黎建宁、李思行一 简介1 目的本规范的目的是使开发人员以标准的、 规范的方式编写代码， 养成良好的编码风格和习惯， 形成公司内部编码约定， 提高程

2、序的可读性， 可维护性以及一致性，同时减少项目组成员间技术沟通成本，提高团队开发效率。2 范围1、本文档基于 Java1.5的语法描述编码规范。2、本文档从代码风格、注释、命名、声明以及异常处理等五个方面对Java编码进行约定。3、本规范适用于所有运用Java 技术的软件项目、产品。4、本规范适用的文件类型包括但不限于Java源文件、JSP 文件、XML 文件、HTML 文件、 JS 文件以及 AS 文件。5、本规范建议采用统一的Code Style 以及 Formatter 风格，通过 IDE 进行配置。3 读者范围1、软件过程改进领导小组以及工作小组所有人员；2、所有运用 Java 技术的

3、软件项目、产品的相关领导、项目负责人、设计人员、开发人员以及测试人员。3、所有涉及运用 Java 技术的软件项目、产品的相关人员。二 代码风格1 缩进1、使用空格代替Tab 缩进，避免各种编辑器中看到不一样的代码格式。 【注：强制执行， Eclipse 可辅助排版】2、代码按层级缩进，每层级缩进4 个字符（对于特定格式文件，可以按照实际进行调整，如XML 文件可缩进 2 个字符），所有“”块内容都应该进行缩进。【注：强制执行， Eclipse 可辅助排版】参考例子：2 括号1、除数组的初始化定义外， “”中的语句应单独作为一行。 。【注：强制执行， Eclipse 可辅助排版】2、左括号“”可

4、根据开发习惯是否换行存放，如果换行存放，必须与其前导语句首字符对齐，右括号“ ”必须作为单独一行存放并且与匹配行对齐（即左括号前导语句首字符） 。【注：强制执行， Eclipse 可辅助排版】3、在项目内部，相同类型的文件，其括号的风格必须统一。【注：强制执行， Eclipse 可辅助排版】参考例子：3 空格1、操作符两端必须带有空格符。 【注：强制执行， Eclipse 可辅助排版】参考例子：2、各并行元素（如函数参数）间以空格符隔开，空格符放在逗号后方。参考例子：【注：强制执行， Eclipse 可辅助排版】3、无特别要求，括号“ ”、“ ”、“ ()”左右方尽量不要增加无必要性的空格符。

5、【注：强制执行， Eclipse 可辅助排版】参考例子：4 空行1、同一个编译单元间（包定义、导入声明、类）应以空行相隔。参考例子：【注：强制执行， Eclipse 可辅助排版】2、类定义内部各元素间（字段定义、方法）应以空行相隔。参考例子：【注：强制执行， Eclipse 可辅助排版】3、同一方法内实现不同的功能之间应以空行相隔。【注：强制执行】4、不能无理由出现大片空行。 【注：强制执行】5 控制语句1、对于循环控制等元素块，不管是否带有body，都应该以 包含。参考例子：【注：强制执行】6 行宽1、每行代码尽量控制行宽在100 字以内，当超出100 字时候，代码应当进行缩进。【注：非强制

6、执行，属加分项】2、方法的缩进应当保证参数对齐。 【注：非强制执行，属加分项】参考例子：3、对于过长的 SQL/HQL 语句，则采用关键字对齐方式， 具体可通过 PL/SQL 等工具进行代码的格式化。 【注：非强制执行，属加分项，附带 sql 规范一并考核】参考例子：7 类、函数1、每个函数的代码长度应尽量控制在 50 行以内（不包含注释），如果函数功能过于庞大， 可把独立的功能段单独抽取出来作为子函数。 【注：非强制执行，属加分项】2、每个类的代码长度应尽量控制在1000 行以内（不包含注释），如果类功能过于庞大，可通过组合的方式来分解类。【注：非强制执行，属加分项】三 注释1 基本原则1、

7、注释目的在于增加代码清晰度，使代码易于被其他开发人员理解。【注：强制执行】2、保持注释简洁，禁止为了注释而注释。【注：强制执行】3、注释除带有代码功能外，还应带有描述上下文意图，具体描述其原因。4、除变量定义等较短语句的注释可用行尾注释外，其他注释当避免使用行尾注释。5、对描述较长的注释，应当使用HTML标记进行格式化，便于生成的JavaDoc易阅读和理解。【注：强制执行】2 文件、包1、文件、包头部应当带有注释，描述其功能、作用、作者、创建时间、修改历史等信息。【注：非强制执行，属加分项】参考例子：3 类、接口1、对类、接口的注释应当符合JavaDoc 规范。【注：强制执行】2、类、接口定义

8、必须标记功能、作用、作者、时间。【注：强制执行】3、当代码基线定义后，后续维护中新增的方法或字段在类、接口声明头部中应当添加修订记录，注明时间、原因以及作者。【注：非强制执行，属加分项】参考例子：4 方法1、对方法的注释应当符合JavaDoc规范。【注：强制执行】2、方法定义应带有功能、作用、执行条件（如果有）、参数，对于复杂功能的方法，应当带有例子描述。【注：功能、作用、执行条件（如果有） 、参数属强制执行；例子描述属非强制执行，属加分项】3、每个方法中含有的参数以及返回值应当描述其类型、作用、值的范围，对方法的影响。【注：强制执行】4、当方法抛出自定义的受控异常（Checked Excep

9、tion，不含工具、框架抛出的异常）时，必须对异常产生的原因进行描述，便于调用者捕捉。【注：强制执行】参考例子：5、对规范中约定的方法，如回调方法、 getter/setter 方法，只要遵守其命令约定，均不需要编写注释。 【注：非强制执行】参考例子：6、如果方法内部涉及复杂的算法、关键步骤或难以理解的语句，应当添加注释标明其含义。【注：非强制执行，属加分项】7、对于超过一行注释， 必须采用 “ /* */ ”进行标注， 而单行注释可采用 “/”标注。【注：强制执行】5 变量1、全局变量、静态变量、类中的字段应当带有注释。【注：强制执行】参考例子：2、对规范中约定的变量，如注入对象（如Serv

10、ice、DAO ），通讯对象（如RemoteObject），只要遵守其命令约定，均不需要编写注释。【注：非强制执行，属加分项】参考例子：3、对于方法内部产生的临时变量，应当尽量添加注释，标明其中的作用。四 命名1 基本原则1、文件，类，函数，变量，命名必须采用可准确表达其意义的英文单词。2、命名不能和关键字相同。 【注：强制执行】3、尽量避免使用出现误解的词汇。4、不允许使用拼音命名，全部使用英文单词或缩写命名。【注：强制执行】2 文件、包1、文件名第一字母应大写。 【注：强制执行】2、文件名应尽量描述该文件作用。 【注：非强制执行，但采用拼音命名需扣分】3、文件名应使用名词或形容词名词。 【

11、注：强制执行】4、包名一般以项目或模块名进行命名，采用小写。【注：强制执行】5、包名组成规则 基本包 . 项目名 . 模块名 . 子模块名 . 【注：强制执行】参考例子：6、禁止把类直接定义在默认包下。以下行为必须禁止：【注：强制执行】3 类、接口1、类、接口名第一字母应大写。 【注：强制执行】2、类名应尽量描述该类作用。 【注：强制执行】3、类名应使用名词或形容词名词。 【注：强制执行】4、如果需要用到多个单词表达其意义，每个单词第一个字母必须用大写标识。【注：强制执行】参考例子：5、类名不使用下划线。【注：强制执行】6、如果用到某些特定名词作为类名，应保持该特定名词， 如“ADOHelpe

12、r ”。【注：强制执行】7、接口的第一个字母应为“ I ”，其他命名规则与普通类名相同。 【注：强制执行】8、对于 DAO 类，其命名规则为：名词+“ DAO ”，对于应用服务类，其命名规则为：名词 +“ Service”。【注：强制执行】9、如果类为持久类，需要与数据库表进行绑定的，其命名在忽略前缀以及下划线等特殊字符的情况下，应与数据库表名保持一致。【注：强制执行】以下行为必须禁止：4 字段1、字段名第一字母应小写。 【注：强制执行】2、字段名应尽量描述该字段的作用。 【注：强制执行】3、字段名应使用名词或形容词名词。 【注：强制执行】4、如果需要用到多个单词表达其意义，除第一个字母外，每

13、个单词第一个字母必须用大写标识。【注：强制执行】5、如果字段所在类为持久类，需要与数据库表进行绑定的，其命名在忽略前缀以及下划线等特殊字符的情况下，应与数据库字段名保持一致。【注：强制执行】5 方法1、方法名第一字母应小写。 【注：强制执行】2、方法名应尽量描述该方法的作用。 【注：强制执行】3、方法名应使用“动词名词”形式命名。【注：强制执行】4、如果需要用到多个单词表达其意义，除第一个单词外，其他单词第一个字母必须用大写标识。【注：强制执行】5、对于常用的DAO 查询方法，方法应当表明方法出处、数据的来源以及查询依据。如getOrderListByCustomer 方法根据顾客获取订单列表

14、，此方法由Order 模块提供而不是Customer 模块。【注：（ 1）强制执行，但条件定义为非强制执行，即 getOrderListByCustomer 中的 ByCustomer 为非强制执行】6、回调方法应使用“ Callback”作为方法后缀，如非特殊回调方法，可采用“调用方法 +Callback”命名规则，如 login 方法回调，其方法命名为 loginCallback。【注：强制执行】7、Flex 各种事件，采用“ on”作为方法前缀命名，如非特殊事件，可采用 “ on+ 方 法 名 ” 命 名 规 则 ， 如 createComplete 事 件 中 ， 其 方 法 命 名

15、为onCreateComplete，如果存在多个相同的事件，采用“ on+组件 ID+ 方法名”命名规则。【注：强制执行】6 变量1、变量名第一字母应小写。 【注：强制执行】2、变量名应尽量描述该变量的作用。3、变量名一般使用 “形容词名词” 或单个名词，布尔变量应使用含有 “判断意义的单词名词” ，例如判断是否已关闭的变量： boolean isClosed，禁止声明类似 aaa、 bb 无法定义、理解的变量。 【注：强制执行】4、如果需要用到多个单词表达其意义，除第一个单词外，其他单词第一个字母必须用大写标识。【注：强制执行】5、用于 for 循环的局部变量可使用i 等单个字母。【注：非强

16、制执行】7 常量1、常量名应尽量描述该常量的作用。 【注：非强制执行，但采用拼音命名需扣分】2、常量名一般使用“形容词名词”或单个名词。【注：强制执行】3、如果需要用到多个单词表达其意义，单词间应通过“_”分割。【注：强制执行】参考例子：8 组件变量1、组件变量符合变量命名规则。 【注：强制执行】2、组件变量名一般采用组件前缀+变量名命名。【注：强制执行 ,表单内的组件变量非强制执行】3、一般情况下，组件前缀可采用组件缩写 （见本章第 9 节 Flex 命名约定表）或全名表示，但对于过长的组件命名，建议采用缩写标识。（新增的必须执行）【注：强制执行，因考虑其对旧项目的改动性太大，故该考核只针对

17、新增的代码模块 ,其中 Flex 命名约定表里的组件若需要缩写标识,则必须是 Flex 命名约定表中对应的缩写标识】4、对于某些显示数据库字段的控件，其变量名应对应数据库字段名。【注：强制执行】9 附 Flex 命名约定表组件全名组件名称缩写Controls类：AdvancedDataGridAlertButtonCheckBoxColorPickerComboBoxDataGridDateChooserDateFieldHSliderHorizontalListImageLabelLinkButtonListNumericStepperOLAPDataGridPopUpButtonPopUp

18、MenuButtonProgressBarRadioButtonRadioButtonGroupRichTextEditorSWFLoaderTextTextAreaTextInputTileListTreeVSliderVideoDisplayadgalbtnchkcrpcmbdgdcdfhslhorlstimglbllnkbtnlstnsodgpubpumbprgrdordogrtxswfltxtxatxitlttrevslvdpLayout类：ApplicationControlBarCanvasControlBarFormFormHeadingacbcvsctbfmfmhGridgdH

19、BoxhbHDividedBoxhdbHrulehrModuleLoadermdlPanelpnlSpacerspcTiletilTitleWindowtilwVBoxvbVDividedBoxvdbVRulevrNavigators 类：AccordionaodButtonBarbtnbLinkBarlkbrMenuBarmnbTabBartabTabNavigatortbnToggleButtonBartbbViewStackvskCharts 类：AreaChartarecBarChartbarcBubbleChartbubcCandlestickChartcancColumnChart

20、colcHLOCCharthloccLegendlgdLineChartlincPieChartpiecPlotChartploc自定义组件根据基础组件进行自定义组合注意：基于约定优于配置原则， 若规范中定义的命名规则与组件约定的规则存在冲突，以组件约定的规则为优先。参考例子：五 声明1 类、接口1、可见性必须显式声明。【注：强制执行】2 方法1、可见性必须显示声明。【注：强制执行】2、尽可能减少类与类之间耦合，尽量限制成员函数的可见性（不要扩大其可见范围）。【注：非强制执行，属加分项】3、如果存在多个参数，按照功能的相似性，应放到一齐。【注：强制执行】4、对于同样可见性的方法，按照功能的相似性，应放到一齐。（如 as 中应当将事件、回调方法、引用方法区分存放）。【注：强制执行】5、对于重载的方法，按参数的个数，从少到多排序。【注：强制执行】6、方法按照其属性以及可见性，按以下顺序排序：构造方法、静态公共方法、静态私有方法、受保护方法、私有方法、以及继承自Object 的方法（ as 代码按照实际情况进行调整） 。【注：强制执行】7、方法的声明顺序按照以下优先级声明：功能相似性-可见性 - 参数个数列子：public void saveUser(User user)public void saveUser(User user, Long o