在Android项目里，命名和注释看似琐碎，却是决定团队协作效率的关键因素。一个含糊的类名会导致新人不敢修改旧代码，一段错误的注释比没有注释更危险。命名约定解决的是如何让代码在最短时间内被读懂的问题，注释风格则决定哪些信息被记录、哪些噪音被排除。可以从四个层面入手：先确立命名原则，再按Android组件和资源类型拆解规则，随后明确注释边界，最后用工具把规范固定下来。
一、命名约定要优先保证可读性和一致性
命名的首要目标是让阅读者不需要跳转到定义处就能理解变量或方法的大致用途。在Android代码里，最应该避免的是拼音、无意义缩写和类型冗余。比如用d表示天、用strName表示姓名字符串、用flag表示任意状态，这些名字在单人开发时似乎够用，但进入多人协作后就会造成大量猜测。更合适的做法是让名字直接表达业务含义和单位，例如elapsedTimeInMs表示以毫秒计的耗时，isNetworkAvailable表示网络是否可用。
// 不推荐：缩写、拼音、类型冗余 int d; String strName; boolean flag; // 推荐：明确业务含义和单位 int elapsedTimeInMs; String userName; boolean isNetworkAvailable;
Android工程与普通Java或Kotlin项目有一个明显区别：它包含大量资源文件。布局、字符串、颜色、尺寸、图片资源都需要命名，而且这些名字会直接出现在R类和XML引用里。资源命名应当包含资源类型、业务模块和用途。例如布局文件可以写成activity_main.xml、fragment_order_detail.xml，图标可以写成ic_add_black_24dp.png。字符串资源不要用text1、label这类顺序命名，而应该写成login_button_text、order_status_paid，让引用处一眼能看出语义。
<resources>
<string name="login_button_text">登录</string>
<string name="order_status_paid">已支付</string>
<color name="color_primary">#3F51B5</color>
<dimen name="list_item_height">48dp</dimen>
</resources>
Java和Kotlin在命名上还需要区分语言习惯。Java中常量通常使用static final修饰，并采用全大写下划线风格；Kotlin则更推荐使用const val或val，顶层常量可以直接定义在文件顶部。Kotlin属性本身已经包含类型信息，不应再写userNameString或者ageInt这类冗余后缀。类名保持名词或名词短语，方法名保持动词或动词短语，布尔值方法建议使用is、has、can开头，这些规则在两种语言中基本一致。
const val MAX_RETRY_COUNT = 3
class UserRepository(
private val remoteDataSource: UserRemoteDataSource,
private val localDataSource: UserLocalDataSource
) {
fun fetchUser(userId: Long): User {
// 先查本地缓存，未命中时请求远程接口
return localDataSource.getUser(userId) ?: remoteDataSource.getUser(userId)
}
}
二、按Android组件和资源类型拆解命名规则
Android组件类的命名应该体现组件类型和页面职责。Activity类以Activity结尾，Fragment以Fragment结尾，Adapter以Adapter结尾，ViewModel以ViewModel结尾。例如登录页可以命名为LoginActivity，订单列表可以命名为OrderListFragment。这样不仅能降低搜索成本，也能避免把网络请求类误认为页面类。包名则建议沿用公司域名倒置规则，并在末尾按模块分层，例如com.example.order.payment、com.example.order.detail。
资源文件命名需要和组件类名以及业务模块对应。布局文件用前缀区分类型，例如activity_、fragment_、item_、dialog_，后面的部分使用模块和页面描述。控件ID使用小驼峰，前缀可以标注控件类型，比如tvUserName表示TextView，btnSubmit表示Button，rvOrderList表示RecyclerView。字符串资源按照模块分组，使用下划线连接，不要用默认的app_name之外再放一堆hello_world这种无意义内容。
方法名和变量名需要更细的粒度约束。获取数据的方法可以用load、fetch、query开头，处理事件的方法用handle、on开头，创建对象的方法用create或工厂方法命名。集合类型变量使用复数，例如users、orderItems，单个对象使用单数。布尔变量避免使用status、check这类不明确词语，而应该写成isLoading、hasError、canRetry。循环中的临时变量可以简短，但要避免和外部变量重名。
// 方法命名体现动作和返回值
public void loadUserProfile() {}
public boolean hasValidToken() { return true; }
public List<User> searchUsers(String keyword) { return Collections.emptyList(); }
// 集合与布尔变量示例
private List<Order> paidOrders;
private boolean isLoading;
private boolean hasMoreData;
三、注释风格：解释为什么，而不是复述代码
注释最大的误区是逐行翻译代码。如果代码本身已经足够清晰，再写一句将age加1并不会增加信息量，反而增加阅读负担。好的注释应该解释代码无法表达的内容，比如为什么选择某个算法、为什么加一层缓存、为什么在某个边界条件下做特殊处理。比如在年龄递增处，如果逻辑与生日跨天有关，就应当写明这个业务背景，而不是简单说明变量加一这个操作。
// 不推荐：复述代码 // 将 age 加 1 int newAge = age + 1; // 推荐：解释业务背景和边界 // 生日当天年龄递增，避免跨天缓存导致显示偏差 int newAge = age + 1;
类注释和方法注释需要形成统一模板。Android工程里可以继续沿用JavaDoc或KDoc风格，用@param说明参数含义，用@return说明返回值的单位和可能为空的情况，用@throws说明异常条件。类注释最好能写清该类在哪个模块、承担什么职责、依赖哪些核心对象。但注释也要避免记录作者和修改日期这类可以通过版本控制获取的信息，避免形成无效噪音。
/**
* 计算商品折后价格。
*
* @param originalPrice 原价，单位：分
* @param discountRate 折扣率，范围 0.0 到 1.0
* @return 折后价格，单位：分
*/
public int calculateDiscountedPrice(int originalPrice, float discountRate) {
return (int) (originalPrice * discountRate);
}
对于未完成的工作，建议使用统一的TODO和FIXME标记，并注明负责人和具体事由。TODO表示计划内尚未实现的功能，FIXME表示存在缺陷需要修复。不要把大段被注释掉的旧代码留在文件里，这些代码会让后续维护者无法判断是临时禁用还是废弃逻辑。复杂业务判断之前可以用简短注释说明规则来源，例如退款金额计算涉及平台补贴时，需要写明补贴比例依据哪份需求文档，而不是只写计算退款金额。
// TODO(zhangsan): 接入后端接口后移除本地假数据 // FIXME: RecyclerView 在快速滑动时偶发 IndexOutOfBounds，待用 DiffUtil 解决 // 退款金额 = 用户实付金额 - 平台补贴，补贴比例见需求 PRD-1024 BigDecimal refundAmount = paidAmount.subtract(platformSubsidy);
四、借助工具和评审让规范持续生效
规范如果只停留在文档里，很快就会被遗忘。Android项目可以在Gradle中集成静态检查工具，例如Kotlin项目使用detekt，Java项目使用Checkstyle，XML资源可以使用自定义Lint规则。将命名检查、注释模板检查、禁止注释代码检查纳入本地构建和CI流水线，一旦提交了不符合规范的代码，构建阶段直接失败。这样规范就从个人自觉变成了工程约束，减少评审时的重复沟通。
// build.gradle.kts 中启用 detekt
plugins {
id("com.android.application")
id("org.jetbrains.kotlin.android")
id("io.gitlab.arturbosch.detekt")
}
detekt {
buildUponDefaultConfig = true
config = files("$rootDir/config/detekt.yml")
}
Android Studio本身也提供了一些模板能力。团队可以提前配置Live Templates，让新建Activity、Fragment、ViewModel时自动生成符合规范的文件头注释和类结构。对于方法命名、常量命名和变量命名，可以配置IDE的Inspections，将不符合约定的模式标记为警告或错误。例如禁止变量名中包含类型后缀、禁止使用单字母变量名等，这些规则可以在团队内共享配置文件，避免每个开发者各自为政。
<module name="MethodName">
<property name="format" value="^[a-z][a-zA-Z0-9]*$"/>
</module>
工具无法覆盖所有场景，最终的判断仍然需要Code Review。评审时应当关注命名是否表达业务含义、注释是否解释了关键决策、是否存在被注释掉的旧代码、资源ID是否与页面职责一致。团队可以整理一份简短的检查清单，每次提交只花几分钟扫一遍。规范也不是一成不变的，如果某个规则长期造成误解，就应该在团队内讨论并更新。命名和注释的本质是降低认知成本，而不是追求形式上的整齐，因此任何规则都应当服务于可读性和维护效率。
Android代码规范命名约定注释风格修改时间：2026-09-29 12:22:01