外观

本页目录

注释规范 ​

代码大区块之间可以回车换行，且有有单独的中文注释。小模块或者内容备注前面需要携带大模块或者功能的名称，以中划线分隔。 必须加注释的地方：

  • 公共组件使用说明
  • api 目录的接口 js 文件必须加注释
  • store 中的 state, mutation, action 等必须加注释
  • vue 文件中的 template 必须加注释，若文件较大添加 start end 注释
  • vue 文件的 data, 非常见单词要加注释
  • vue 文件中，在引用其他方法时，也需要加注释
  • vue 文件的 methods，每个 method 必须添加注释。无参数或者比较简单函数可以单行备注，有参数和复杂函数需要多行备注。

整体规范 ​

注释名内容含义
@description文件、方法描述描述该功能模块的作用
@author作者信息描述此函数作者的信息
@version版本号描述版本信息
@param参数名 {类型} 描述描述此函数入参的信息
@return返回值 {类型} 描述描述此函数返回的信息
  • 通用的.css, .js：@description @author @version
  • 项目下公共.js：@description
  • 公共方法：@description @param @return

html注释 ​

html
<!-- header头部 -->
<header>
<div class="logo"></div>
</header>
<!-- 布控模块 -->
<section>
...
</section>

css注释 ​

块级注释统一用 /* xxx */

scss
/* 关键词标签 */
@mixin tag-keyword($color, $bdcolor) {
    display: inline-block;
    padding: 8rpx 28rpx;
    color: $color;
    border: 2rpx solid $bdcolor;
    border-radius: 200rpx;
}
.keywords {
    @include tag-keyword(#32AE57, rgba(50,174,87,0.60));
}
.keywords-uncheck {
    @include tag-keyword(#333333, #DDDDDD);
}

js注释 ​

块级注释 ​

块级注释，包括对文件的整体注释，以及方法块注释

js
data: function () {
    return {
        //布控
        controlLoading: false,  //布控loading
        controlAnalysisObj: {  //布控统计
            date: '2050-10-1'  //布控统计日期
        }
    }
},
created(){
    // header-总体分析-解析柱状图
    this.changeAnalysis();
    // 布控-布控统计-请求列表数据
    this.getControlList();
},
method:{
    //public-返回当前时间年份
    returnDate(){
    return new Date().getFullYear()
},
 /*
  * @description: 布控-布控统计图
  * @param {Boolean} 是否显示线条
  * @param {Array} 统计图的数据
  * @return 没有返回信息写 void / 有返回信息 {返回类型} 描述信息
  */
controlChart(showLine,chartData){
...
}
vue的style备注示例：
//header头部
.header{
  .logo{
    width:100px;
  }
}
//布控
.control{
...
}
js
/**
 * @description 正则校验
 */

const mobileReg = /^1\d{10}$/
const emailReg = /^\w+([-+.]\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*$/
const specialCharReg = /[`~!@#$%^&*()_\-+=<>?:"{}|,./;'\\[\]·~！@#￥%……&*（）——\-+={}|《》？：“”【】、；‘’，。、]/
const emojiReg = /\ud83c[\udf00-\udfff]|\ud83d[\udc00-\ude4f]|\ud83d[\ude80-\udeff]|[\uD800-\uDBFF][\uDC00-\uDFFF]/

/**
 * @description 四舍五入保留n位小数
 * @param {Number} num 初始数值
 * @param {Number} n 小数位数，默认1位
 * @param {Boolean} isFixed 小数位是否补0，默认否
 * @return {Number} 小数值
 */
const countDecimal = (num, n = 1, isFixed = false) => {
  if (isFixed) {
    return Number(num.toFixed(n))
  } else {
    const reg = new RegExp('([0-9]+.[0-9]{' + n + '})[0-9]*')
    return Math.round(num * Math.pow(10, n)) / Math.pow(10, n).toString().replace(reg, '$1')
  }
}

/**
 * @description 过滤特殊符号
 * @param {String} str 文本字符串
 * @param {String} key 替换的内容，默认空
 * @return {String} 过滤掉特殊符号的字符串
 */
const filterSpecialChar = (str, key = '') => {
  return str.replace(new RegExp(specialCharReg, 'g'), key)
}

/**
 * @description 过滤表情符号
 * @param {String} str 文本字符串
 * @param {String} key 替换的内容，默认空
 * @return {String} 过滤掉表情符号的字符串
 */
const filterEmoji = (str, key = '') => {
  return str.replace(new RegExp(emojiReg, 'g'), key)
}

export {
  mobileReg,
  emailReg,
  emojiReg,
  specialCharReg,
  countDecimal,
  filterSpecialChar,
  filterEmoji,
}

全局变量注释 ​

vuex 数据状态管理的变量必须注释

js
// store/state.js
const state = {
  appId: 'wx01d071fbf6dac44c', // 应用的唯一标识
  openId: null, // 一个用户打开一个微信应用（公众号、小程序）的唯一标识
  unionId: null, // 同一用户，对同一个微信开放平台下的不同应用，unionid是相同的
}

页面变量注释 ​

单个.vue页面，基础的、全局的、路由传进来的变量必须注释，例：type entrance 等

定义规则：是否关系用0,1；平级关系用1,2,3...；默认值为Number类型

js
data () {
  return {
    type: 1, // 1视频 2图文 3快速咨询
    entrance: 1, // 1就诊人管理 2药店端扫码添加就诊人 3购药补充信息 4白处方补充信息
  }
}

逻辑注释 ​

方法中复杂易混淆的逻辑必须注释

如果在书写代码时，业务逻辑过于复杂，需要在特定的地方加上辅助注释信息，以备后来开发人员理解业务

在 GitHub 上编辑此页

上次更新: