模块应通过命名导出、简短JSDoc注释、语义化目录结构和统一index.js入口实现“自解释”，降低跨团队理解成本。
模块化本身不自动产生文档，但配合规范的导出方式、结构约定和轻量注释，就能让模块“自解释”，大幅降低跨团队理解成本。关键不是堆砌文档工具，而是让代码结构和接口定义本身就传递足够信息。
用命名导出明确暴露意图
避免默认导出一个大对象，优先使用命名导出。每个导出名应准确反映其职责，比如 validateEmail、formatCurrency、debounce，而不是笼统的 utils 或 helper。调用方看到 import { validateEmail } from './validation' 就能立刻知道用途，无需查源码或文档。
每个模块配简短的 JSDoc 块（非强制但强推荐）
在模块顶层加 2–4 行中文注释，说明「它是什么」和「谁该用它」，不写实现细节：
- 不要写：“内部使用正则校验邮箱格式”
- 要写：“对外提供邮箱格式校验，用于表单提交前验证；不处理网络请求或后端逻辑”
目录即契约：靠文件结构传递上下文
模块所在路径本身就是重要文档。例如：
立即学习“Java免费学习笔记（深入）”；
-
features/payment/services/AlipayClient.js→ 表明这是支付功能下的支付宝对接服务，属业务层，非通用工具 -
shared/utils/date.js→ 表明这是跨功能复用的日期工具，无业务耦合 -
features/user/hooks/useUserProfile.js→ 表明这是 React 自定义 Hook，专用于用户资料场景
团队成员按路径就能判断模块边界、复用范围和变更影响面，比读一段文字描述更直接。
统一入口 + index.js 聚合，收敛调用点
每个功能目录下设 index.js，只做两件事：导出本模块对外承诺的 API，重命名或组合子模块导出。例如：
export { default as ApiClient } from './services/ApiClient';
export { login, logout } from './services/auth';
export { useAuth } from './hooks/useAuth';
外部只需 import { login, useAuth } from '@/features/user'，不必关心内部怎么分文件。重构时只动 index.js，调用方完全无感——这本身就是最稳定的“接口文档”。
