总览

前端开发在编写公司项目代码的原则和思路：

  • 符合 web 标准（UTF-8，HTML5）。
  • 语义化 html（HTML5 语义化标签，相对减少 div 和 span 等无特定语义的标签使用）。
  • 结构表现行为分离（HTML-CSS-JS 代码分离，不同行为代码分离，做到高内聚低耦合）。
  • 网站呈现效果要保持多主流浏览器 UI 展示一致，移动端和 PC 端设备兼容无错乱。
  • 浏览器兼容要求满足 chrome，firefox,Edge 等主流或相同内核的浏览器。对于已存在的 vue2 项目兼容到 ie11 及以上。
  • 页面性能方面（减少无意义的请求次数，例如使用精灵图和预编译 css 语法）。
  • 代码要求简洁明了有序，尽可能的减小服务器负载，保证最快的解析速度（减小 repaint 和 reflow）。
  • 项目需要清晰和规范的命名，这对于了解快速熟悉一个项目是有益的。
  • 对代码进行注释对于提高可读性有帮助，需要在业务逻辑和公共方法里面把条件和逻辑都详细备注好，在功能迭代和调整后也需要在代码片段相应增加注释。

文件命名

  • 所有文件夹及文件使用英文命名。避免使用中文路径，使用中划线命名风格。

  • 项目命名，中划线方式的英文命名，且框架项目 package 里面的 name 应和项目名保持一致。

  • 前端资源按 html，css，js，img，font 基础类别分类，对应文件均存放至项目的对应文件名目录中。如果使用相关前端框架，根据框架的文件格式进行合理布局。

  • html 文件：入口文件使用 index.html。每个频道和栏目按照英文称呼原则酌情做到清晰命名。

// 推荐命名
|- index.html // 首页
|- list.html // 列表页
|- detail.html // 详情页
|- /components // 分类频道文件夹/公共组件文件夹
  |-filter.html // 筛选器页面/模块
  |-form.html // 表单页面/模块
  |-operate-box.html // 操作栏页面/模块或者更细的颗粒单元组件等等
  ...
  • css 文件命名：后缀.css（预编译工具使用 less）。首页或唯一的 css 文件 index.css，其他页面按照对应的 html 命名。
// 推荐命名（以less举例）
|- index.less
|- variable.less // 全局变量单元
|- initialize.less // 初始化通用规则（标签，行高，重置属性等等）
|- base.less // 基础样式单元
|- element-ui.less // 复写ui库的样式单元（以elementUi为例）
|- tab-bar.less // 详细的公用样式单元等等
...
  • JS 文件命名：后缀.js。唯一或者主要的用 index.js，其他页面按照对应的 html 命名。由于 JS 文件在前端框架业务中也会分散在单元模块里，独立的 JS 文件目录会相对更简洁一些。
// 推荐命名
|- index.js // 唯一或者主JS
|- common.js // 统一调用的公共方法集合
|- validate.js // 独立完整的功能单元JS（以验证功能为例）
...
  • img 和 iconfont 相关资源类文件命名：与命名规范主思路保持一致即可。
// 推荐命名
|- /img
  |- banner.png
  |- hot-icon-01.jpg
|- /iconfont
  |- iconfont.ttf

注释规范

前端开发的html，css，js相关的文件，都需要用头部注释来统一展示内容格式，目的是为了方便查阅和管理参与者，更新时间等等基础数据。

现提供标准格式，项目参与者复制后，配置自己的编辑器后，新建项目和维护项目文件的时候可以使用和更新。

头部模板

/*
 *
 * @author: your name
 * @date: 2022-05-13
 * @description: 组件模板信息
 *
 */

函数/方法模板

/*
 *
 * @param {string} uid - 用户id
 * @return {User} 一个用户
 *
 */

VSCode的全局配置snippets代码片段，可复制后直接使用。或者自行下载各类型自动创建的头部注释的插件。更详细的IDEA、VSCode模板配置示例

{
  "HTML头部注释": {
    "scope": "html,vue",
    "prefix": "annh",
    "body": [
      "<!--",
      " *",
      " * @Author: $1",
      " * @Date: ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}",
      " * @Description: $2",
      " *",
      " -->"
    ],
    "description": ""
  },
  "JS头部注释": {
    "scope": "css,less,javascript,typescript",
    "prefix": "annj",
    "body": [
      "/*",
      " *",
      " * @Author: $1",
      " * @Date: ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}",
      " * @Description: $2",
      " *",
      " */"
    ],
    "description": ""
  }
}

除此之外，我们规定在业务代码里面，如果有比较多自定义的属性名，比如props里面的各种id，userId,detailId等等，也需要注释清楚各种参数的命名意义，方便后续读取代码的时候节省理解力。更多的还是需要开发人员对于命名的准确性的概括，越清晰的命名规范越能体现专业的开发素质，这方面需要命名和注释双向的配合。

项目文档

项目文档规范作为一个项目的入口，提供给参与者一个大致对项目的整体认知，我们规定项目根目录下面的README.md文件作为项目文档的存放位置。我们需要在这里呈现这些信息：

  • 项目的安装
  • 进入项目的开发模式
  • 对项目打包指令的描述
  • 项目具体的分支规划细则
  • 项目包含的关键模块
  • 项目包含的关键依赖 我们提供了一个基础的，业务项目中可以择情填写和扩展项目的重要信息。

一级规范

使用正确的缩进
以下类型文件使用2个空格缩进，禁止使用tab或4个空格缩进：

.js(x)
.ts(x)
.css
.less
.html
.json
.yml
.xml
.vue

禁止在函数内做与函数名称以及注释不相符的操作
一个函数应当只做一件事情，所做的事情必须与函数名称以及注释相关

恰当的命名
命名必须含义明确
不使用区分度较低的命名
禁止使用非标准的缩写以及自造词
名称中不要包含类型
类名、字段名使用名词或名词短语
方法名使用动词或动词短语
一个词对应一个概念，禁止一词多义
一个概念对应一个词，禁止一义多词

禁止迷惑行为
禁止在常规方法中进行特殊处理，或进行与上线文以及方法签名及描述不相关的操作或处理
如果因既有的设计缺陷需要进行特殊处理，必须在方法的注释内进行说明，并在相关处理的代码前添加注释

将代码放进正确的包或模块
应当在正确的模块下面添加代码，禁止随意放置代码

禁止过长的方法和类
类的长度不得大于800行

方法的长度不得大于100行

禁止参数过多的方法
禁止方法参数超过5个，尽量避免参数超过3个

禁止过于复杂的嵌套逻辑
条件判断以及循环的嵌套层数不能超过5层

项目依赖

  • 所有npm run build需要的依赖都必须放在dependencies；

  • 所有npm run dev不需要的依赖都必须放在devDependencies。

如果你不知道无法判断依赖是否必须，则将它放在dependencies中，而eslint和prettier之类的与代码格式相关而与业务无关的依赖都应当放在devDependencies中。