规范的核心是提升可维护性而非约束手感：命名需语义明确，分层要职责单一，JavaDoc须完整准确，依赖须注入而非硬编码，以此保障修改安全与协作高效。
规范不是为了约束你写代码的手感，而是为了让别人（包括三个月后的你自己）能不翻源码就看懂你在干什么。
为什么改一行代码要花两小时？——命名和注释不规范的代价
变量叫 a、tmp、dataList，方法叫 doWork() 或 handle()，这类命名在单人小项目里看似省事，但只要交接、重构或排查 Bug，就会立刻暴露问题：没人知道 dataList 是用户列表还是日志缓存，handle() 到底 handle 了什么异常还是只是个空壳。
- 类名用大驼峰：
UserRegistrationService，而不是userservice或UsrRegSrv - 方法名动词开头+业务语义：
sendVerificationEmail(String email)，而非process(String s) - 所有 public 方法必须有完整 JavaDoc，含
@param、@return、@throws，哪怕只有一行逻辑
反例：/** @param x xxx */ public void f(int x) { ... } —— “x” 和 “xxx” 对维护毫无帮助；正例：/** 发送邮箱验证码，失败时抛出 MailSendException */ public void sendVerificationEmail(String email) { ... }
为什么加个新字段就崩了整个服务？——结构与职责混乱的连锁反应
把数据库查询、参数校验、消息推送、日志记录全塞进一个 saveUser() 方法里，短期快，长期就是技术债黑洞。一旦要换短信通道、加风控规则、或对接新审计系统，就得动这个“万能方法”，每次修改都像拆炸弹。
- 严格分层：Controller 只做请求映射和简单 DTO 转换，Service 封装业务原子动作，Repository 只管 CRUD
- 每个类只做一件事：一个
UserRegistrationValidator类专责校验，一个EmailNotificationService专责发信，用接口解耦，方便 mock 和替换 - 避免在 Service 层直接 new 对象，依赖应通过构造函数注入，否则单元测试无法隔离
典型坏味道：new EmailSender().send(...) 出现在 service 方法体中 —— 这让测试必须真实发邮件，也锁死了通知渠道。
为什么 CI 总是报 “Javadoc missing”？——JavaDoc 不是摆设，是契约
IDE 的自动补全、Swagger 的 API 文档、CI 流水线里的 doclint 校验，全靠 JavaDoc 提供结构化元数据。
-
@param必须覆盖所有入参，且说明取值范围（如 “非 null”、“长度 ≤ 50”） -
@return要明确是否可能为 null，或返回空集合 vs null 集合的区别 -
@throws不仅写异常类型，更要说明触发条件（如 “当email格式非法时抛出IllegalArgumentException”）
工具链会扫描这些标签生成文档、检查遗漏、甚至在编译期报错。关掉 doclint（如 Maven 中配置
最常被忽略的一点：规范的价值不在“写得漂亮”，而在“改得放心”。当你删掉一个没人调用的 private 方法时，如果它没 JavaDoc、没单元测试、名字又叫 helper()，你敢删吗？
