Alibaba开发规范_编程规约之命名风格

命名风格的基本原则

1. 命名不能以下划线或美元符号开始或结束

反例：

_name = "John"
__name = "Doe"
$name = "Jane"
name_ = "Smith"
name$ = "Brown"
name__ = "Taylor"

解释： 虽然有些开源代码使用下划线开头，但这种风格在Python中通常表示内部变量。为了保持一致性，建议避免使用下划线或美元符号作为命名的开始或结束。

2. 严禁使用拼音与英文混合或直接使用中文

反例：

int DaZhePromotion = 10; // 打折
void getPingfenByName() { // 评分
    // ...
}

正例：

int discountPromotion = 10;
void getScoreByName() {
    // ...
}

解释： 使用正确的英文拼写和语法可以避免歧义，提高代码的可读性。

3. 类名使用 UpperCamelCase 风格，但以下情形例外：DO / BO / DTO / VO / AO / PO / UID 等

正例：

class UserDO {
    // ...
}
class XmlService {
    // ...
}

反例：

class userDo {
    // ...
}
class XMLService {
    // ...
}

解释： 类名应使用大驼峰命名法，但一些特定缩写（如DO、DTO、VO等）可以例外。

• DO（ Data Object）：与数据库表结构一一对应，通过DAO层向上传输数据源对象。
• DTO（ Data Transfer Object）：数据传输对象，Service或Manager向外传输的对象。
• BO（ Business Object）：业务对象。 由Service层输出的封装业务逻辑的对象。
• VO（ View Object）：显示层对象，通常是Web向模板渲染引擎层传输的对象。
• AO (Application Object) :应用对象,在 Web 层与 Service 层之间抽象的复用对象模型,极为贴近展示层,复用度不高。
• POJO 是 DO / DTO / BO / VO 的统称.

4. 方法名、参数名、成员变量、局部变量使用 lowerCamelCase 风格

正例：

void getHttpMessage() {
    int localValue = 10;
    // ...
}

解释： 方法名、参数名、成员变量和局部变量应使用小驼峰命名法。

5. 常量命名全部大写，单词间用下划线隔开

正例：

final int MAX_STOCK_COUNT = 1000;
final long CACHE_EXPIRED_TIME = 3600;

反例：

final int maxCount = 1000;
final long expiredTime = 3600;

解释： 常量命名应全部大写，单词间用下划线隔开，以提高可读性。

6. 抽象类命名使用 Abstract 或 Base 开头，异常类命名使用 Exception 结尾

正例：

abstract class AbstractUser {
    // ...
}
class UserNotFoundException extends Exception {
    // ...
}

解释： 抽象类和异常类的命名应遵循特定的命名规则，以便于识别。

7. 数组类型与中括号紧挨相连

正例：

int[] arrayDemo = new int[10];

反例：

int arrayDemo[] = new int[10];

解释： 数组类型应与中括号紧挨相连，以提高代码的可读性。

8. POJO 类中布尔类型变量不要加 is 前缀

反例：

class User {
    private boolean isDeleted;
    // getter and setter
}

正例：

class User {
    private boolean deleted;
    // getter and setter
}

解释： 布尔类型变量不加 is 前缀，以避免框架解析时出现序列化错误。

9. 包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词

正例：

package com.alibaba.ai.util;

解释： 包名应使用小写，点分隔符之间应有一个自然语义的英语单词。

10. 避免在子父类的成员变量之间或不同代码块的局部变量之间采用完全相同的命名

反例：

class ConfusingName {
    public int age;
    public void getData(String alibaba) {
        if (condition) {
            final int money = 531;
            // ...
        }
        for (int i = 0; i < 10; i++) {
            final int money = 615; // 与上面的 money 同名
            // ...
        }
    }
}

解释： 避免在子父类的成员变量之间或不同代码块的局部变量之间使用相同的命名，以提高代码的可读性。

11. 杜绝完全不规范的缩写

反例：

class AbsClass { // AbstractClass 的缩写
    // ...
}

正例：

class AbstractClass {
    // ...
}

解释： 避免使用不规范的缩写，以确保代码的可读性。

12. 使用尽量完整的单词组合来表达其意

正例：

class AtomicReferenceFieldUpdater {
    // ...
}

反例：

int a; // 随意命名

解释： 使用完整的单词组合可以提高代码的自解释性。

13. 表示类型的名词放在词尾

正例：

long startTime;
Queue<String> workQueue;
List<String> nameList;
int TERMINATED_THREAD_COUNT;

反例：

long startedAt;
Queue<String> QueueOfWork;
List<String> listName;
int COUNT_TERMINATED_THREAD;

解释： 表示类型的名词应放在词尾，以提高辨识度。

14. 命名时体现出设计模式

正例：

class OrderFactory {
    // ...
}
class LoginProxy {
    // ...
}
class ResourceObserver {
    // ...
}

解释： 在命名时体现出设计模式，有助于阅读者快速理解架构设计理念。

15. 接口类中的方法和属性不要加任何修饰符号

正例：

interface UserService {
    void commit();
    String COMPANY = "alibaba";
}

反例：

interface UserService {
    public abstract void f();
}

解释： 接口中的方法和属性应保持简洁，避免不必要的修饰符号。

16. 接口和实现类的命名规则

正例：

interface CacheService {
    // ...
}
class CacheServiceImpl implements CacheService {
    // ...
}

解释： 接口和实现类的命名应遵循特定的规则，以便于识别和理解。

17. 枚举类名带上 Enum 后缀，枚举成员名称需要全大写

正例：

enum ProcessStatusEnum {
    SUCCESS,
    UNKNOWN_REASON
}

解释： 枚举类名应带上 Enum 后缀，枚举成员名称应全大写。

18. 各层命名规约

A) Service/DAO 层方法命名规约

class UserService {
    User getUserById(int id) { // 获取单个对象
        // ...
    }
    List<User> listUsers() { // 获取多个对象
        // ...
    }
    int countUsers() { // 获取统计值
        // ...
    }
    void saveUser(User user) { // 插入
        // ...
    }
    void deleteUser(int id) { // 删除
        // ...
    }
    void updateUser(User user) { // 修改
        // ...
    }
}

B) 领域模型命名规约

class UserDO { // 数据对象
    // ...
}
class UserDTO { // 数据传输对象
    // ...
}
class UserVO { // 展示对象
    // ...
}

解释： 各层的命名应遵循特定的规约，以便于识别和理解。

结语

良好的命名风格是编写高质量代码的基础。通过遵循上述规约，开发者可以提高代码的可读性、可维护性和可扩展性。