H5 移动端、管理系统 开发规范文档

开发规范的目的是保证统一项目成员的编码风格,并使代码美观,易于项目维护。

1.命名规范

1.1 项目文件命名
  • 项目名:
    全部采用小写方式,优先选择单个单词命名, 以短横线分隔。例:my-project-name。
  • 目录名:
    参照项目命名规则,有复数结构时,要采用复数命名法。例:assets、components、utils、views等。
  • 图像文件名:
    全部采用小写方式,优先选择单个单词命名,短横线分隔。例pic-people.jpg。
  • HTML 文件名:
    全部采用小写方式,优先选择单个单词命名, 以短横线分隔。例:home-page.html。
  • CSS 文件:
    全部采用小写方式,优先选择单个单词命名, 以短横线分隔。例:home-page.css。
  • JavaScript 文件名:
    全部采用小写方式,优先选择单个单词命名, 以短横线分隔。例:home-page.js。
1.2 Vue 组件命名
  • 组件名:
    文件扩展名为 .vue。应该始终是单词大写开头。例:MyComponent.vue。
  • 紧密耦合的组件名:
和父组件紧密耦合的子组件应该以父组件名作为前缀命名。 因为编辑器通常会按字母顺序组织文件,所以这样做可以把相关联的文件排在一起。例:
|-TodoList.vue
|-TodoListItem.vue
|-TodoListItemButton.vue
  • 组件名中单词顺序:
    组件名应该以高级别的 (通常是一般化描述的) 单词开头,以描述性的修饰词结尾。 因为编辑器通常会按字母顺序组织文件,所以现在组件之间的重要关系一目了然。如组件主要是用于搜索和设置功能。例:SearchButtonClear.vue
1.3 代码参数命名
  • router
    Vue Router Path 命名采用 kebab-case 格式。 用camelCase(如:/userInfo)的单词会被当成一个单词,搜索引擎无法区分语义。
    component 采用懒加载写法引入。
 {
    path: '/my-router',
    name: 'MyRouter',
    component: () => import("@/views/home/index.vue"),
    meta: {
      title: '标题',
      desc: '描述'
    }
  }
  • 模板中组件
    对于绝大多数项目来说,在单文件组件和字符串模板中组件名应该总是 PascalCase 的,但是在 DOM 模板中总是 kebab-case 的。
    在单文件组件和字符串模板中:
<MyComponent/>

在所有地方:

<my-component></my-component>
  • 变量
命名方法:camelCase
命名规范:类型 + 对象描述或属性的方式
  • 常量
命名方法:全部大写下划线分割
命名规范:使用大写字母和下划线来组合命名,下划线用以分割单词
  • 方法
  命名方法:camelCase
  命名规范:统一使用动词或者形容词 + 名词形式
  • 自定义事件
  命名方法:camelCase
  命名规范:统一使用动词或者形容词 + 名词形式
  • 事件方法
  命名方法:camelCase
  命名规范:handle + 名称(可选)+ 动词

2.代码规范

  • Vue
1. 代码结构
<template></template>
<script></script>
<style></style>
2. 为 v-for 设置键值
 在组件上必须用 key 搭配 v-for,以便维护内部组件及其子树的状态。
3. v-if 和 v-for 互斥
 永远不要把 v-if 和 v-for 同时用在同一个元素上。

3.注释规范

  • HTML 文件注释
1.单行注释

一般用于简单的描述,如某些状态描述、属性描述等。
注释内容前后各一个空格字符,注释位于要注释代码的上面,单独占一行。

<!-- Comment Text -->
<div>...</div>
2.模块注释

一般用于描述模块的名称以及模块开始与结束的位置。
注释内容前后各一个空格字符,模块与模块之间相隔一行。

<!-- S Comment Text A --> 
<div class="mod_a">
  ...
</div>
<!-- E Comment Text A -->
3.CSS 文件注释

3.1 单行注释:
注释内容第一个字符和最后一个字符都是一个空格字符,单独占一行,行与行之间相隔一行。

/* Comment Text */ 
.jdc {} 

3.2 模块注释:
注释内容第一个字符和最后一个字符都是一个空格字符,/ 与 模块信息描述占一行,多个横线分隔符 - 与 / 占一行,行与行之间相隔两行。
推荐:

/* Module A  
---------------------------------------------------------------- */
.mod_a {}


/* Module B 
---------------------------------------------------------------- */
.mod_b {}
  • JavaScript 文件注释:
1.单行注释

单行注释使用 //,注释应单独一行写在被注释对象的上方,不要追加在某条语句的后面。

// is current tab
const active = true
2.多行注释

多行注释使用 /* … /,而不是多行的 //。

/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make (tag) {
  // ...
 return element
}
3.注释空格

注释内容和注释符之间需要有一个空格,以增加可读性。eslint: spaced-comment。

// is current tab
const active = true
4.特殊标记

有时我们发现某个可能的 bug,但因为一些原因还没法修复;或者某个地方还有一些待完成的功能,这时我们需要使用相应的特殊标记注释来告知未来的自己或合作者。常用的特殊标记有两种:

// FIXME : 说明问题是什么
// TODO : 说明还要做什么或者问题的解决方案
5.文档类注释

文档类注释,如函数、类、文件、事件等;都使用 jsdoc 规范。

/**
 * Book类,代表一个书本.
 * @constructor
 * @param {string} title - 书本的标题.
 * @param {string} author - 书本的作者.
 */
function Book (title, author) {
 this.title = title
 this.author = author
}

4.版本管理

  • 主分支(master)
    代码合并到正式分支之前现将正式分支代码合并到主分支,始终落后正式分支一个版本。
  • 正式分支(prod)
    用于对外发布版本,任何时候在这个分支获得的代码都是线上最新版本。
  • 预生产分支(pre)
    用于发布预生产环境。
  • 测试分支(test)
    用于发布测试环境。
  • 功能分支(按照功能描述命名)
    开发某项特定功能,从prod分支上面分出来的;开发完成后,合并到test分支进行测试。
  • 补丁分支(按照Bug描述命名)
    修复正式环境bug分支,从prod上分支出来;开发完成后,再合并到test分支上进行测试。

5.其它

  • Node.js版本 v16+。
  • Vue版本 v3+。
  • UI组件库 移动端:vant;管理系统:element-plus;
  • 状态管理使用 Vuex 或 Pinia。
  • 遵循 ESLint + Prettier 的代码规范。
  • 使用 Axios 进行网络请求,封装请求模块,统一错误处理和loading状态管理。
  • 根据业务需求合理使用缓存策略。
  • 路由配置清晰,区分动态路由和静态路由。
  • 部署流程自动化,使用 Jenkins/Git 工具,找运维人员部署正式环境。
最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
平台声明:文章内容(如有图片或视频亦包括在内)由作者上传并发布,文章内容仅代表作者本人观点,简书系信息发布平台,仅提供信息存储服务。

推荐阅读更多精彩内容

  • 一、项目目录规范 项目名 项目名要求使用语义清晰,简短,统一使用英文小写,并且使用-隔开,后缀要加-wx以区分是小...
    旋风猫阅读 1,942评论 0 1
  • 一、 目录结构 二、 UI框架选择 PC端Vue项目UI框架优先选择:Element UI、iView移动端Vue...
    zhudying阅读 4,557评论 4 28
  • 包名全部采用小写,不用下划线区分单词 主包名采用[公司性质].[公司名称].[项目名称]的命名方式 例如:翡翠教育...
    gyymz1993阅读 3,184评论 1 29
  • android规范文档,请勿转载!谢谢... 1. 概述 1.1 前言团队协作能够显著有效的提高工作效率,而代码规...
    kai_w阅读 2,059评论 1 2
  • React-Native开发规范 标签(空格分隔): React-Native JavaScript 一、编程规约...
    德山_阅读 1,598评论 1 0