VJTools项目中的Java命名规范详解

VJTools项目中的Java命名规范详解

vjtools The vip.com's java coding standard, libraries and tools 项目地址: https://gitcode.com/gh_mirrors/vj/vjtools

前言

在Java开发中，良好的命名规范是代码可读性和可维护性的基础。VJTools项目作为一套Java工具集，对命名规范有着严格的要求。本文将详细解读VJTools项目中的命名规约，帮助开发者编写更规范的Java代码。

基本命名原则

1. 禁止使用拼音缩写

问题：拼音缩写会极大降低代码的可读性，特别是对于不熟悉中文的开发者。

示例：

// 错误示例
DZ // 打折
getPFByName() // 获取评分

// 应尽量避免
Dazhe
DaZhePrice

建议：优先使用准确的英文单词，如"discount"代替"dazhe"。

2. 避免非标准缩写

问题：随意的缩写会导致理解困难，特别是当不同开发者使用不同缩写时。

示例：

// 错误示例
AbsClass // AbstractClass的缩写
condi // condition的缩写

建议：除非是行业公认的缩写(如HTTP、TCP等)，否则应使用完整单词。

命名风格规范

1. 包命名规范

包名应全部小写，点分隔符之间尽量只包含一个单词：

// 正确示例
com.vip.javatool

// 错误示例
com.vip.java_tool
com.vip.javaTool

2. 类和接口命名

采用UpperCamelCase(大驼峰)风格：

// 正确示例
UserId
XmlService
TcpUdpDeal
UserVO

// 错误示例
UserID
XMLService
TCPUDPDeal
UserVo

特殊类型命名建议：

• 枚举类：以Enum结尾，如DealStatusEnum
• 抽象类：以Abstract或Base开头，如AbstractView
• 异常类：以Exception结尾，如TimeoutException
• 测试类：以被测试类名开头，以Test结尾，如UserServiceTest

3. 方法、变量命名

采用lowerCamelCase(小驼峰)风格：

// 正确示例
localValue
getHttpMessage()

4. 常量命名

全大写，单词间用下划线分隔：

// 正确示例
MAX_STOCK_COUNT

// 错误示例
MAX_COUNT

例外情况：

1. 当static final字段不是基本类型时：

private static final Logger logger = Logger.getLogger(MyClass.class);

2. 枚举常量虽推荐全大写，但历史原因未遵循也是允许的。

高级命名技巧

1. 体现设计模式

在类名中体现使用的设计模式，有助于快速理解代码结构：

OrderFactory // 工厂模式
LoginProxy // 代理模式
ResourceObserver // 观察者模式

2. 接口与实现类命名

实现类建议使用Impl后缀：

CacheServiceImpl implements CacheService

但对于形容能力的接口，可不使用Impl后缀：

Foo implements Translatable

3. 避免命名冲突

重要规则：

1. 子类成员变量不应与父类成员变量同名
2. 方法参数/局部变量不应与类成员变量同名(getter/setter除外)

错误示例：

public class A {
  int foo;
}

public class B extends A {
  int foo; // 错误：与父类成员同名
  int bar;

  public void hello(int bar) { // 错误：与成员变量同名
    int foo = 0; // 错误：与成员变量同名
  }
}

常见陷阱

1. 布尔类型命名

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

// 错误示例
private Boolean isSuccess; // 可能导致序列化问题

// 正确示例
private Boolean success;

2. 模糊命名

避免以下模糊命名方式：

1. 使用a1, a2, a3等编号命名
2. 方法参数与局部变量名仅差一个前缀(如bookList与theBookList)
3. 同一应用中存在Account、AccountInfo、AccountData等相似类名
4. 拼写极度接近的名称(callerId与calleeId)

总结

VJTools项目的命名规范强调"清晰表达意图"的核心原则。通过遵循这些规范，可以显著提高代码的可读性和可维护性。记住，好的命名应该让阅读者无需额外注释就能理解其含义，这是编写高质量Java代码的基础。

vjtools The vip.com's java coding standard, libraries and tools 项目地址: https://gitcode.com/gh_mirrors/vj/vjtools