Java common development specifications

1 Background overview

As a member of the programmers army, the author works in Shenyang Shutongchanglian Software Technology Co., Ltd. On the first day of my tenure, I heard the leader emphasize the importance of development specifications, but I still wondered why development specifications are the most important. Shouldn’t it be all good if the function is implemented?

Over time, I have also gone through several software projects and have become more and more aware of the importance of developing specifications. Today, the author summarizes what I have heard, learned and personal summary to share with you, hoping to provide you with help.

2 Purpose meaning

In the case of team collaborative development, a set of distinct programming styles can make collaborators, successors and themselves clear at a glance, see the structure of the program in a very short time, and understand the design ideas. Improve code readability, reusability, program robustness, portability, and maintainability. The purpose of formulating development specifications is to improve the efficiency of software development and the maintainability of the developed software, and to improve the quality of the software. Improve your own logical thinking ability through the constraints of development norms, and also improve your personal coding ability and level.

3 Development Specifications

As a developer of a software project, the primary requirement for functional code is that the code must be correct, ensure that the function is operational, and can meet the needs of customers. The second requirement is that the code must be clear and easy to understand, so that other programmers can easily understand the principle of the code, enhance the readability of the code, and ensure a uniform and consistent programming style of the code. Next, we clarify the development specification through several aspects such as format, naming, permissions, and performance.

3.1 Unified format

• Overall style

1. Use a ladder hierarchy to organize program code. Each level of indentation is 4 spaces, with parentheses on the next line. The matching braces are required to be in the same column, and the next line should also be indented by 4 spaces. The reference code is as follows:
2. The definition of variables should be located at the beginning of the function as much as possible. For global variables/static variables, the definition should be between the class name and the constructor.
3. A space indicates a split, separated by a space on both sides with a space operator. For example, a + b = c, a+b=c is not allowed; if the comma statement is not OK, you need to follow the comma with a space, such as: call(a, b, c); cannot call(a,b,c ).

• method definition

1. For the definition of a unified method style, the effective code length of a single function should be within 100 lines as much as possible, which can further ensure that the code logic is clearly visible.
2. Logically related sequence codes and their preceding and following program codes should be separated by blank lines; blank lines should be inserted between comment sections and program sections, as well as in different program sections. Improve readability.
3. A single class should not be too large. When such a class is too large, the code of the corresponding function should be refactored into other classes and invoked by combination, etc. It is recommended that the length of a single class including comment lines should not exceed 1500 lines. Try to avoid large classes and long methods.

• nested relationship

1. The number of nesting levels of IF statements should be kept within 3 levels as far as possible, and the FOR/WHILE loop should be two-level loop as much as possible. If you exceed the limited number of layers, you should consider that your code logic is adjustable.
2. The number of Boolean operators (&&, ||) in a Boolean expression in the same IF condition does not exceed 10.

3.2 Naming conventions

• package name definition

1. The first few of the package names are fixed names, usually the company's domain name/project fixed name and then the project name. If the domain name has not been determined, the company's fixed names will be used. Such as: com.agileai.wm
2. The next word in the package name is the name of the module. Such as: user module, the package name is com.agileai.wm.user
3. All packages must be named in lowercase English letters. Names contain business semantics that quickly convey the purpose of the class. Regarding the access operation of the module, it adopts a hierarchical form and is generally divided into:

Model layer operation: generally defined in com.agileai.wm.user.module.service, where user is the module name.

Controller layer operation: generally defined in com.agileai.wm.user.module.handler.

View layer operation: generally defined in the file path and the corresponding registration.

• class name definition

1. Referring to the java camel case nomenclature, the first letter of the class name must be capitalized. If the class name is composed of multiple words, the first letter of each word must be capitalized. Such as: ForumManagePostPortlet.java
2. Naming is chosen to have business semantics and quickly communicate the purpose of the class. The reference model is as follows:

模型(model)层操作：一般定义为，接口类：ForumProvider.java   接口实现类：ForumProviderImpl.java。

控制器(controller)层操作：一般定义为XXXHandler，如：ForumPostLocatorHandler。

视图(view)层操作：一般定义为：XXX.jsp，如：ForumUserEdit.jsp。

• 方法命名

1. 选择有意义的名字，能快速地传达该方法的用途。参照java驼峰命名法，首字母以小写开头，每个单词首字母大写（第一个单词除外）。
2. 对数据操作的方法命名通常以insert（插入）,delete（删除）,update（更新）,select（查找）,count（统计）开头。获取批量数据通常定义为findXXXRecords()，获取单条记录通常为getXXXRecord()。
3. 在进行方法名名师通常会根据方法的行为命名，描述方法的意义，而不采用方法的目的命名。如：系统的添加新用户，用户可以前台注册，也可以管理员后台添加，方法会被重用，最好不要用使用register，采用add会更好写。

• 变量命名

1. 驼峰命名法，当变量名或函式名是由一个或多个单字连结在一起，而构成的唯一识别字时，首字母以小写开头，每个单词首字母大写（第一个单词除外）
2. 静态变量通常采用全部大写的形式来书写，对于采用多词合成的变量采用“_”来连接各单词。如：USER_LIST
3. 除非是在循环中，否则一般不推荐使用单个字母作为变量名，i、j、k等只作为小型循环的循环索引变量。
4. 如果需要对变量名进行缩写时，一定要注意整个代码中缩写规则的一致性。例如，如果在代码的某些区域中使用intCnt，而在另一些区域中又使用intCount，就会给代码增加不必要的复杂性。建议变量名中尽量不要出现缩写。

3.3 权限定义

1. public修饰符：它具有最大的访问权限，可以访问任何一个在CLASSPATH下的类、接口、异常等。它往往用于对外的情况，也就是对象或类对外的一种接口的形式。通常在通用调用、跨模块调用时选择public修饰符。
2. protected修饰符：它主要的作用就是用来保护子类的。它的含义在于子类可以用它修饰的成员，其他的不可以，它相当于传递给子类的一种继承的东西。通常在需要继承时选择。
3. default修饰符：什么都不写就是default，它是针对本包访问而设计的，任何处于本包下的类、接口、异常等，都可以相互访问，即使是父类没有用protected修饰的成员也可以。
4. Private修饰符：它的访问权限仅限于类的内部，是一种封装的体现，例如，大多数的成员变量都是修饰符为private的，通常不希望被其他任何外部的类访问时选择private。

4 代码封装

作为面向对象的语言-JAVA，其三大基本特征就是封装、继承以及多态。其中封装是继承与多态的基础。通过封装不仅可以使代码逻辑更加清晰，同时也可以实现最小调整达到全局调整的目的。通过程序的代码的封装也可以提升复用率减少代码的冗余程度。下面我们介绍常见的需要封装的几种场景如：本类复用、多类调用等。

4.1 本类复用

1. 在实现代码封装之前需要明确不同修饰符的访问权限，其中public为公共调用，private为私有调用，protected为继承调用。
2. 在本类中多次引用相同处理逻辑的程序代码，需要将其统一进行提取封装为公共调用的方法，并将其的访问权限定义为private最大程度的确保程序的安全性。
3. 在本类中多次引用的相同的变量值（通常为用于比较的固定字符串或者静态的变量值）需要将其定义在类名与构造函数之间，保证在后续维护过程中可以实现最小调整即可调整全局的目的。

4.2 多类调用

1. 对于被多处引用的结果属性，通常将其封装为对象类，将其属性定义为变量，并初始set、get方法对齐赋值或者取值。
2. 对于某些属性变量值被多处调用，我们通常将被调用的属性变量值定义在一个公共类中，并将其定义为static变量，保证在其他环境引用是可以直接使用类名.变量名进行调用。
3. 在实现业务功能需求如Excel导入、导出，打印等功能，其功能可为单独提取实现，通常我们将撰写Helper帮助类（XXXHelperHandler）提供实现功能，以便业务功能调用实现需求。

4.3 代码重构

1. 无论是在项目中还是日常的工作中，对于代码的重构均是不可缺少的，通常我们可以将公共的方法提取出来放在一个新的Handler中利用新的Handler继承BaseHandler原有的Handler继承新创建的Handler。
2. 如果公共方法不能完全复用，可以将公共的逻辑提取出来放在新的XXXHelperHandler中，在Handler中进行调用方法即可。

5 优势说明

5.1 降低成本

• 好的开发规范可以尽可能的减少一个软件的维护成本，虽然在开发过程中要符合开发规范的条条框框看似浪费时间，但是从长远的软件代码维护来看更清晰的代码逻辑更节省交接以及维护是时间。降低了项目/产品的维护成本。
• 好的开发规范可以增强软件代码的可读性，良好的编程规范可以实现代码的自注释，可以让产品/项目的后续开发人员直观明确的了解代码的逻辑，较大幅度的降低了因代码逻辑混乱造成的工作交接困难，进一步影响了整个项目/产品的开发（运维）周期。通过周期的缩短减少人力的投入降低项目/产品的人员成本。

5.2 提高效率

好的开发规范可以最大限度的提高团队开发的效率；良好的开发规范可以保证代码风格的统一，保证整个项目/产品的开发风格是一致的，即使人员变更维护或者进行排错推断也可以减少因编程风格不统一造成的时间浪费。

5.3 能力提升

长期的规范性编码还可以促使开发人员养成良好的编程习惯，通过代码的逻辑性也可体现出开发人员的逻辑思维，不断提升自己的开发的规范性也可以从侧面提升个人逻辑思维能力。

6 个人总结

笔者作为数通畅联软件技术有限公司中的一名技术人员，从开始参加工作个人对公司强行要求开发规范的不理解至今深度认知开发规范的重要性。笔者在数通畅联这个大家庭中，每天耳濡目染学习java常见的开发规范如：命名、权限、格式等。通过自身的调整以及认知的提升也逐步提升了个人的编码能力。

笔者认为一个良好的编码习惯不仅体现出个人的能力水平，也体现出其所在环境，所在团队的整体风气。希望大家今后都可以培养自己的编码习惯使开发规范中的硬性要求成为自己的下意识习惯。