15. 前端项目规范（目录 / 命名 / 注释）

规范听起来很无聊，但它是"团队协作的地基"。你一个人写代码随便乱命名无所谓，但团队里十几个人一起改一个项目——你的代码别人 3 秒看不懂，沟通成本就爆炸。规范的核心就是让代码"见名知意"，不用读细节就知道大概干嘛的。

三个最基本的：目录别堆一起（分开放）、命名别乱起（有规律）、注释别废话（写为什么不写是什么）。

15.1 互动演示（命名规范小测验）

15.2 知识点讲解

① 项目目录分层规范（别全堆根目录）

很多新手项目打开根目录全是文件——html、css、js、图片全混在一起，找个文件要翻半天。规范的做法是按类型分文件夹：

// 首页页面
project / ├──index.html
// 登录页面
├── login.html
// 其他业务页面
├── pages /
  // 订单页面
  │└──order.html
// 样式文件夹
├── css /
  // 公共通用样式（重置、按钮、弹窗）
  │├──common.css
// 订单页独立样式
│└── order.css
// JS 文件夹
├── js /
  // 工具函数
  │├──utils /
  // 请求封装
  ││└──request.js
// 接口管理
│├── api /
  // 用户接口
  ││├──user.js
// 订单接口
││└── order.js
// 全局公共逻辑
│├── common.js
// 页面业务逻辑
│└── pages /
  // 订单页面逻辑
  │└──order.js
// 图片资源
├── images /
  // 第三方库（jQuery 等）
  └──lib /

② 文件、变量、函数命名规范

// ===== 文件命名 =====
// html 页面：全小写，单词用短横线
user - list.html
// css 同上
order - detail.css
// js 工具/接口文件：小驼峰
userApi.js
// 文件夹：全小写 + 短横线
user - info /


  // ===== 变量命名 =====
  // 普通变量：小驼峰
  let userName = "张三";
// 常量（固定不变的）：全大写 + 下划线
const BASE_URL = "http:           // ...";
// jQuery 对象：前面加 $ 区分原生 DOM
const $submitBtn = $("#submit");
// 布尔值：用 is/has/can 开头
let isLoading = false;
// 禁止：let a, b, c 这种单字母、中文命名、拼音命名


// ===== 函数命名：动词 + 名词 =====
// 获取数据
getUserList
// 新增
addOrder
// 更新
updateInfo
// 删除
deleteItem
// 渲染页面
renderTable
// 事件处理函数：handle 开头
function handleSearch() {}
// 禁止：func1、test 这种没意义的名字

// 文件头部注释（工具/接口文件必须写）
/**
 * 用户相关接口
 * @author 你的名字
 * @description 用户新增、查询、登录请求封装
 */

// 函数文档注释（通用工具、请求函数）
/**
 * 通用接口请求
 * @param {string} method 请求方式 GET/POST
 * @param {string} url 接口路径
 * @param {Object} data 请求参数
 * @returns {Promise} 后端返回数据
 */
// 单行注释：解释"为什么这么写"，不是复述代码
function request(method, url, data) {}
// 401 代表登录过期，清空 token 后跳登录页
if (res.code === 401) {}

别写废话注释——比如 let num = 10; // 定义一个数字 这就是废话，代码本身已经说明了。注释要解释"为什么这么写"——比如为什么要清 token、为什么这里要特殊处理。

④ 实战：用在哪 / 常见坑 / 怎么解决

可能在什么地方用：

① 团队协作项目必须按规范来，不然别人看不懂；② 自己的项目过半年回头看，不规范自己都看不懂自己写的啥。

常见的问题：

① 所有文件堆根目录，找文件找半天；② 变量名起 a、b、temp，过两周忘了是啥；③ 注释全是废话——"这是一个循环"；④ 保留一大段注释掉的废弃代码，看着乱。

解决思路：

① 按上面的目录结构建文件夹；② 命名时多花 3 秒想个有意义的名字；③ 注释写"为什么"，不写"是什么"；④ 不用的代码直接删，别注释留着。

15.3 课后作业（融入本节）