命名规范

前言

统一的命名规范不仅能够提升代码可读性，也能降低多人协作、长期维护以及大型工程扩展时的沟通成本。

命名时应尽量做到：

• 语义明确
• 统一简洁
• 避免歧义
• 便于检索
• 便于长期维护

包命名规范

基本规则

• 包名统一采用小写字母命名
• 禁止使用中文、拼音、大写字母
• 禁止使用特殊字符
• 不建议在包名中使用无意义缩写
• 包结构建议按照 “从通用到具体” 的层级组织

类命名规范

基类

采用 Base + 类型 的命名规则

abstract class BaseActivity { }

abstract class BaseFragment { }

abstract class BaseDialog { }

abstract class BaseDialogFragment { }

abstract class BaseDevice { }

Activity 类

命名规则：业务描述 + Activity

class InitActivity { }

class MainActivity { }

class FlutterModuleActivity { }

Fragment 类

命名规则：业务描述 + Fragment

class HomeFragment { }

class MeasureFragment { }

class FlutterModuleFragment { }

Dialog 类

命名规则：业务描述 + Dialog / DialogFragment

class CommonMessageDialog { }

class LoadingDialog { }

class FaceRecognitionDialogFragment { }

自定义 View

命名规则：功能 + View 类型

class SwitchButton { }

class StatusLayout { }

class RegexEditText { }

Widget 类

Widget 通常是多个 View 的组合控件

命名规则：功能 + Widget

class PullDownPopMenuWidget { } 

class DateSelectWidget { }

Adapter / Holder 类

命名规则：功能 + Adapter 功能 + Holder

class LogDataAdapter { }

class LogDataHolder { }

class LogAlarmDataHolder { }

class LogOperationDataHolder { }

工具类

命名规则：功能 + Util

class LogUtil { } 

class CRCUtil { }

管理类

命名规则：功能 + Manager

class WindowManager { }

class SerialPortManager { }

class DownloadManager { }

帮助类

命名规则：功能 + Helper

class DatabaseHelper { }

class PermissionHelper { }

异常类

异常类通常继承于 Exception 类，所以采用异常类型 + Exception 的命名规则

class NullPointerException { }

class NetworkException { }

接口和实现类

接口命名应体现：

• 行为能力
• 抽象职责
• 功能特征

不建议使用无意义命名。

1. 业务型接口

例如：Repository / Api 接口

interface UserRepository { }

interface DeviceApi { }

实现类：

class UserRepositoryImpl implements UserRepository { }

2. 行为型接口

命名规则：功能 + Action 功能 + Handler 功能 + Strategy 功能 + Factory

// 动作接口
public interface HandlerAction { }

public interface ClickAction extends View.OnClickListener { }

// 处理器接口
public interface ErrorHandler { }

public interface EventHandler<T> {
    void handleEvent(T event);
}

// 策略接口
public interface SortingStrategy {
    
    <T> List<T> sort(List<T> items);
}

// 工厂接口
interface BitmapFactory { }

3. 监听接口

命名规则：On + 功能 + Listener

interface OnClickListener { }

interface OnDeviceConnectListener { }

interface OnSerialDataListener { }

4. 能力型接口

对于一些具备明确语义、抽象能力或基础契约性质的接口，建议直接使用功能名称命名

例如，Java 源码中的 List 、Map 等，就直接用功能名称，避免多余修饰

public interface Map<K, V> { }

public interface List<E> extends Collection<E> { }

public interface Serializer { }

public interface Logger { }

注解类

注解类用于描述：

• 标记能力
• 编译期检查
• 运行时元数据
• 等

命名规则：

• 优先使用语义化形容词
• 或使用功能描述

示例：

@interface Nullable { }

@interface NonNull { }

@interface UiThread { }

@interface WorkerThread { }

@interface Deprecated { }

@interface LoginRequired { }

@interface DebugOnly { }

对于用于限制参数取值范围的注解：

@interface NetworkType { }

@interface RequestMethod { }

@interface OrientationMode { }

对于组合型注解：

@interface ActivityScope { }

@interface ApplicationScope { }

设计原则

注解类本身属于“元信息描述”，命名时应尽量偏语义化，而不是偏实现化。

好的注解命名应该做到：“只看名称就能理解约束意义”。

枚举类

枚举类通常用于表达：

• 类型集合（Type）
• 状态集合（State）
• 策略集合（Strategy）
• 生命周期阶段（Stage）
• 模式集合（Mode）

当某个字段的取值范围固定且具有明确业务语义时，可以考虑使用枚举进行表达。

命名规则通常采用明确的业务语义：

• 类型名
• 状态名
• 策略名
• 阶段名
• 模式名

🚫 不建议使用：

• Enum
• TypeEnum
• StatusEnum 这种冗余后缀

类型枚举：

enum NetworkType { }

状态枚举：

enum LoginState { }

策略枚举：

enum RetryStrategy { }

生命周期阶段枚举：

enum TaskState { }

枚举值命名规范

枚举常量统一采用：全部大写 + 下划线

示例：

enum DeviceState {

    NOT_CONNECTED,

    CONNECTING,

    CONNECT_SUCCESS,

    CONNECT_FAIL
}

尽量不要滥用枚举

在 Android 开发中，并不是所有状态都适合使用枚举。

因为 Enum 本质上是对象类型，在某些对性能和内存较为敏感的场景中，需要谨慎使用：

场景	原因
RecyclerView 大量列表数据	数据量大时会增加内存占用
高频状态切换模块	频繁访问时效率低于 int
网络协议字段映射	存在额外序列化转换成本
大规模数据模型	对象规模越大成本越明显
数据库存储字段	最终仍需映射为基础类型
串口协议状态码	协议状态通常直接使用数值
串口指令解析	使用枚举会增加额外映射步骤
设备报警码处理	大量报警码不利于维护
高频数据采集	每秒大量解析会放大性能损耗

因此不要因为个人编码风格偏好而过度使用枚举。

应综合考虑：

• 可读性
• 性能
• 内存占用
• 维护成本
• 业务复杂度

根据实际场景选择最合适的实现方式。

方法命名规范

基本规则

• 采用 lowerCamelCase 驼峰命名
• 方法名应表达明确行为
• 禁止中英文混用
• 禁止拼音命名

例如：

public void setData() { }

public T getData() { }

public removeData() { }

常见方法前缀

前缀	含义
get	获取数据
set	设置数据
load	加载
init	初始化
update	更新
refresh	刷新
parse	解析
create	创建
build	构建
release	释放
destroy	销毁

值得注意的是，在命名方法时需确保方法名清晰表达其作用范围。

比如在 Activity 类中，若有一个用于刷新日志列表数据的方法，直接命名为 refreshData 就远不如 refreshLogListData 这样的命名更清晰直观，便于理解其具体功能。

变量命名规范

基本规则

统一采用：lowerCamelCase （驼峰式）风格

例如：

String authorName;

String previewImageUrl;

成员变量

命名规则：

• 普通私有成员变量：m 开头
• Boolean 类型：is 开头
• 静态变量：s 开头

private boolean isShow;

private String mAuthorName;

public String authorName;

private static Context sApplication;

常量

命名规则：全部大写 + 下划线

public static final String ACTION_LOGIN = "action_login"; 

public static final int MAX_COUNT = 100;

WARNING

• 避免在代码中直接使用字符串而不去定义常量，因为这样会导致一样的字符串在项目里多处出现，日而久之，杂乱无章，不利于维护。
• 常量按照类型分类，全局常量就放置在全局类里，单个类里使用的常量就放到单个类里。

资源文件命名

基本规则

资源文件统一采用：小写字母 + 下划线

布局文件

推荐方案

对于布局文件的命名规范，主流的命名方式一般是 类型 + 模块 如下：

activity_init_xml
activity_main.xml
fragment_home.xml
dialog_login.xml
adapter_msg_log_item.xml
widget_page_title_bar.xml

采用这种命名方式的好处是，res 文件夹下没有层级概念，所有布局文件都在一个平面结构中。通过类型前缀，我们可以方便地根据类型来快速定位和查找对应的布局文件。

其他参考

阿里巴巴 Android 开发手册，其中提到了一种不同的命名规范，采用 模块 + 类型 的规则。

Activity 的 layout 以 module_activity 开头
Fragment 的 layout 以 module_fragment 开头
Dialog 的 layout 以 module_dialog 开头
include 的 layout 以 module_include 开头
ListView 的行 layout 以 module_list_item 开头
RecyclerView 的 item layout 以 module_recycle_item 开头
GridView 的 item layout 以 module_grid_item 开头

这种命名方式的优势体现在：

• 能够明确区分不同模块的布局文件，避免不同模块之间命名冲突
• 当项目逐渐变得复杂，模块化命名可以帮助开发者清晰地识别布局所属模块，减少混淆

图片文件

1. 通用资源

命名规则：用途 + 描述

例如：

ic_add.xml
bg_button_primary.xml

2. 模块化资源

命名规则：模块 + 用途 + 描述

例如：

login_ic_username.xml
home_bg_banner.png

动画文件

命名规则：用途 + 动作

fade_in.xml 渐显动画
slide_up.xml 向上滑动动画
rotate_clockwise.xml 顺时针旋转动画
shake_horizontal.xml 水平方向的震动动画
layout_fall_down.xml 布局下落的动画
window_bottom_in.xml 窗口从底部进入的动画

模块化则：模块 + 用途 + 动作

View ID

基本规则

命名规则：控件缩写 + 功能

例如：

@+id/tv_title
@+id/btn_submit
@+id/iv_avatar
@+id/rv_log_list

常见控件缩写

名称	缩写
TextView	tv
EditText	et
Button	btn
ImageView	iv
RecyclerView	rv
RadioButton	rb
RadioGroup	rg
CheckBox	cb
ScrollView	sv
LinearLayout	ll
RelativeLayout	rl
FrameLayout	fl

自定义 View、Layout、Widget 则自定义缩写

values

1. String

命名规则

• 通用的：common + 功能
• 模块化：模块 + 功能
• 根据情况语义化命名也可

注意做好分类整理，示例：

<resources>
    <!-- 应用名称-->
    <string name="app_name">AppName</string>

    <!-- ******************** 通用的 ******************** -->
    
    <string name="common_network_hint">当前没有网络连接，请检查网络设置</string>
    <string name="common_friendly_reminder">友情提示！</string>
    <string name="common_unknown">未知错误！</string>
    <string name="common_unknown_eng">unknown</string>
    <string name="common_loading">加载中&#8230;</string>
    <string name="common_confirm">确定</string>
    <string name="common_cancel">取消</string>

    <!-- ******************** Activity ******************** -->
    
    <!-- MainActivity  -->
    <string name="menu_home">首页</string>
    <string name="menu_community">社区</string>
    <string name="menu_contact">联系人</string>
    <string name="menu_script_classify">脚本</string>
    <string name="menu_message_log">日志</string>

    <!-- ******************** Dialog ******************** -->

    <!-- 通告弹窗-->
    <string name="notify_message_title">温馨提示！</string>
    <string name="got_it">我知道了</string>
    
    <!-- 日志详情弹窗-->
    <string name="log_explain_title">日志详情</string>
    <string name="log_normal">正常</string>
    <string name="log_warning">警告</string>
    <string name="log_error">错误</string>
    <string name="log_type">日志类型：</string>
    <string name="log_text">日志内容：</string>
    <string name="log_date">创建时间：</string>
    <string name="log_qq">QQ号码：</string>
    <string name="log_qq_name">QQ昵称：</string>
    <string name="log_group">群聊号码：</string>
    <string name="log_group_name">群聊昵称：</string>

    <!-- ******************** Widget/View ******************** -->
    
    <!-- 状态布局 -->
    <string name="status_layout_no_data">空空如也</string>
    <string name="status_layout_error_request">请求出错，请重试</string>
    <string name="status_layout_error_network">网络错误，请重试</string>
    <string name="status_layout_retry">重试</string>
</resources>

2. Color

命名规则

• 语义化命名
• color_色值

建议二者结合使用，示例：

<resources>
    <!-- 白色 -->
    <color name="white">#FFFFFFFF</color>
    <color name="white95">#F2FFFFFF</color>
    <color name="white90">#E6FFFFFF</color>
    <color name="white85">#D9FFFFFF</color>
    <color name="white80">#CCFFFFFF</color>
    <color name="white75">#BFFFFFFF</color>
    <color name="white70">#B3FFFFFF</color>
    <color name="white65">#A6FFFFFF</color>
    <color name="white60">#99FFFFFF</color>
    <color name="white55">#8CFFFFFF</color>
    <color name="white50">#80FFFFFF</color>
    <color name="white45">#73FFFFFF</color>
    <color name="white40">#66FFFFFF</color>
    <color name="white35">#59FFFFFF</color>
    <color name="white30">#4DFFFFFF</color>
    <color name="white25">#40FFFFFF</color>
    <color name="white20">#33FFFFFF</color>
    <color name="white15">#26FFFFFF</color>
    <color name="white10">#1AFFFFFF</color>
    <color name="white5">#0DFFFFFF</color>

    <!-- 黑色 -->
    <color name="black">#FF000000</color>
    <color name="black95">#F2000000</color>
    <color name="black90">#E6000000</color>
    <color name="black85">#D9000000</color>
    <color name="black80">#CC000000</color>
    <color name="black75">#B000000F</color>
    <color name="black70">#B3000000</color>
    <color name="black65">#A6000000</color>
    <color name="black60">#99000000</color>
    <color name="black55">#8C000000</color>
    <color name="black50">#80000000</color>
    <color name="black45">#73000000</color>
    <color name="black40">#66000000</color>
    <color name="black35">#59000000</color>
    <color name="black30">#4D000000</color>
    <color name="black25">#40000000</color>
    <color name="black20">#33000000</color>
    <color name="black15">#26000000</color>
    <color name="black10">#1A000000</color>
    <color name="black5">#0D000000</color>

    <!-- 透明色-->
    <color name="transparent">#00000000</color>
    <!-- 标题黑-->
    <color name="title_black">#FF262626</color>
    <!-- App 样式中引用的主题强调色 -->
    <color name="common_accent_color">#5A8DDF</color>
    <!-- 分割线的颜色 -->
    <color name="common_line_color">#ECECEC</color>
    <!-- 水波纹按压颜色 多用于条目-->
    <color name="common_button_ripple_pressed_color">#FFE5E5E5</color>

    <!-- 进度条颜色 -->
    <color name="progress_bar_color">#ffbaba</color>
    
    <!-- 按钮按压时的颜色 -->
    <color name="common_button_pressed_color">#AA5A8DDF</color>
    <!-- 按钮禁用时的颜色 -->
    <color name="common_button_disable_color">#BBBBBB</color>

    <!-- 对话框确认按钮的文本颜色 -->
    <color name="common_confirm_text_color">#007AFF</color>
    <!-- 对话框取消按钮的文本颜色 -->
    <color name="common_cancel_text_color">#F44336</color>
    
    <color name="color_ef8400">#ef8400</color>
    <color name="color_c75600">#c75600</color>
    <color name="color_333333">#333333</color>
    <color name="color_2b2b2b">#2b2b2b</color>
    <color name="color_999999">#999999</color>
    <color name="color_C5C5C5">#C5C5C5</color>
    <color name="color_EEEEEE">#EEEEEE</color>
    <color name="color_3C3C3C">#3C3C3C</color>
    <color name="color_f0f0f0">#f0f0f0</color>
    <color name="color_707070">#707070</color>
    <color name="color_EBEBEB">#EBEBEB</color>
    <color name="color_010101">#010101</color>
    <color name="color_707072">#707072</color>
    <color name="color_EDEDEF">#EDEDEF</color>
    <color name="color_C01C1C">#C01C1C</color>
    <color name="color_EC0000">#EC0000</color>
    <color name="color_E9E9EA">#E9E9EA</color>
    <color name="color_FFF6F6F6">#FFF6F6F6</color>
</resources>

3. Styles

主题相关的样式，以 Theme 命名结尾，控件样式则以 Style 命名结尾。

命名尽量简洁明了！

示例：

<!-- 应用主题样式 -->
<style name="AppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
    .....
</style>

<!-- 全屏主题样式 -->
<style name="FullScreenTheme" parent="AppTheme">
    .....
</style>

<!-- 闪屏页主题样式 -->
<style name="SplashTheme" parent="FullScreenTheme">
    .....
</style>

<!-- 默认圆角按钮样式 -->
<style name="ButtonStyle" parent="Widget.AppCompat.Button.Borderless">
    .....
</style>

<!-- 不带圆角按钮样式 -->
<style name="RectButtonStyle" parent="ButtonStyle">
    .....
</style>

<!-- 默认文本框样式 -->
<style name="EditTextStyle">
    .....
</style>

<!-- 验证码按钮样式 -->
<style name="CountdownViewStyle">
    .....
</style>

Attrs

命名规则

• 一般 declare-styleable 标签里的 name 和 View 名保持一致
• attr 标签里的 name 命名则按具体的功能语义

示例：

<resources>
    <!-- 缩放的 ImageView -->
    <declare-styleable name="ScaleImageView">
        <!-- 缩放比例 -->
        <attr name="scaleRatio" format="float" />
    </declare-styleable>

    <!-- 按照比例显示的 FrameLayout -->
    <declare-styleable name="RatioFrameLayout">
        <!-- 宽高比例 -->
        <attr name="sizeRatio" format="string" />
    </declare-styleable>

    <!-- 仿 ios 开关按钮 -->
    <declare-styleable name="SwitchButton">
        <!-- 是否选中 -->
        <attr name="android:checked" />
        <!-- 是否禁用 -->
        <attr name="android:enabled" />
    </declare-styleable>

    <!-- 正则表达式编辑框 -->
    <declare-styleable name="RegexEditText">
        <!-- 正则输入限制 -->
        <attr name="inputRegex" format="string" />
        <!-- 常用正则类型 -->
        <attr name="regexType" >
            <!-- 手机号（只能以 1 开头）-->
            <enum name="mobile" value="0x01" />
            <!-- 中文（普通的中文字符）-->
            <enum name="chinese" value="0x02" />
            <!-- 英文（大写和小写的英文）-->
            <enum name="english" value="0x03" />
            <!-- 数字（只允许输入纯数字）-->
            <enum name="number" value="0x04" />
            <!-- 整数（非 0 开头的数字）-->
            <enum name="count" value="0x05" />
            <!-- 用户名（中文、英文、数字）-->
            <enum name="name" value="0x06" />
            <!-- 非空格字符 -->
            <enum name="nonnull" value="0x07" />
        </attr>
    </declare-styleable>
</resources>

Dimens

命令规则正常就是 sp_、dp_，也可以根据功能模块单独定义。

示例：

<resources>
    <!-- 默认分割线大小 -->
    <dimen name="line_size">1dp</dimen>
    <!-- 默认按钮的圆角大小 -->
    <dimen name="button_circle_size">999dp</dimen>
    <!-- 通用对话框圆角大小 -->
    <dimen name="dialog_ui_round_size">15dp</dimen>

    <dimen name="sp_1">1sp</dimen>
    <dimen name="sp_2">2sp</dimen>
    <dimen name="sp_3">3sp</dimen>
    <dimen name="sp_4">4sp</dimen>
    <dimen name="sp_5">5sp</dimen>
    <dimen name="sp_6">6sp</dimen>
    <dimen name="sp_7">7sp</dimen>
    <dimen name="sp_8">8sp</dimen>
    <dimen name="sp_9">9sp</dimen>
    <dimen name="sp_10">10sp</dimen>

    <dimen name="dp_0_1">0.1dp</dimen>
    <dimen name="dp_0_5">0.5dp</dimen>
    <dimen name="dp_1">1dp</dimen>
    <dimen name="dp_1_5">1.5dp</dimen>
    <dimen name="dp_2">2dp</dimen>
    <dimen name="dp_2_5">2.5dp</dimen>
    <dimen name="dp_3">3dp</dimen>
    <dimen name="dp_3_5">3.5dp</dimen>
    <dimen name="dp_4">4dp</dimen>
    <dimen name="dp_4_5">4.5dp</dimen>
    <dimen name="dp_5">5dp</dimen>
    <dimen name="dp_6">6dp</dimen>
    <dimen name="dp_7">7dp</dimen>
    <dimen name="dp_8">8dp</dimen>
    <dimen name="dp_9">9dp</dimen>
    <dimen name="dp_10">10dp</dimen>
</resources>

谨记

统一命名规范的重要性会随着项目规模增长而不断放大。

规范不是束缚，而是团队协作中的共识。