从零开始搞基建(1)——前端代码规范

一、JavaScript

1.1 语言

  • 对所有引用都使用 const,不要使用 var。原因:这样做可以确保你无法重新分配引用,以避免出现错误和难以理解的代码。
  • 如果引用是可变动的,使用 let 代替 var。原因:let 是块级作用域的,而不像 var 属于函数级作用域。
  • 坚持使用全等 === 摒弃相等 ==,原因:相等会进行隐式的类型转换。
  • 使用浏览器全局变量时加上 window 前缀,document 和 navigator 除外。
    参考《语言规范

    1.2 命名

  • 变量、函数、参数、方法、属性使用驼峰式命名(CamelCase),例如 loadingModules。

  • 函数或方法在命名时,建议带上可区分的特定词语,便于全局搜索。
  • 常量、枚举属性使用全部字母大写,单词间下划线分隔,例如 HTML_ENTITY。
  • 类、枚举变量使用Pascal命名法,例如 TargetState。
  • 函数名使用动宾短语,例如 getStyle()。
  • 布尔类型的变量使用 is 或 has 为前缀。
  • Promise对象使用动宾短语的进行时表达,例如 loadingData。

    1.3 React

    如果是组件文件,则使用 PascalCase,如 MyComponent.js。React 组件使用 PascalCase,组件实例使用 CamelCase。
    import ReservationCard from ‘./ReservationCard’
    const reservationItem =
    如果组件是一个目录,则组件主入口命名为 index,如 index.js。对于文件夹中的根组件,使用 index.js 作为文件名,使用文件夹的名字作为组件的名字。
    import Footer from ‘./Footer’
    React DOM 使用小驼峰式命名法来定义属性的名称,而不使用 HTML 属性名称的命名约定,例如 onClick。
    Hooks 只能应用于函数式组件中,只在 React 函数最顶层使用 Hooks。不要在循环,条件或嵌套函数中调用 Hook, 确保总是在你的 React 函数的最顶层调用他们。

    1.4 注释

    单行注释用 //,多行注释用 /*…/。

  • 为函数、方法、变量、事件、文件添加注释,说明其功能。

  • 对于内部实现、不容易理解的逻辑、摘要信息等,尤其要注明核心的细节注释。
  • 对于一些常量,需修饰其含义。
    特殊标记:
  • TODO: 有功能待实现。此时需要对将要实现的功能进行简单说明。
  • FIXME: 该处代码运行没问题,但可能由于时间赶或者其他原因,需要修正。此时需要对如何修正进行简单说明。
  • HACK: 为修正某些问题而写的不太好或者使用了某些诡异手段的代码。此时需要对思路或诡异手段进行描述。
  • XXXX: 该处存在陷阱。此时需要对陷阱进行描述。

    1.5 参数设计

  • 一个函数的参数控制在 6 个以内。

  • 有些函数的参数并不是作为算法的输入,而是对算法的某些分支条件判断之用,此类参数建议通过一个 options 参数传递。

    二、图片

    2.1 大小

    中国普通家庭的宽带基本能达到8Mbps,实际速率大约为500—900KB/s,全国3G/4G用户占有比超过了50%,为了保证图片能更好地加载展示给用户看,约定:

  • PC平台单张的图片的大小不应大于 200KB。

  • 移动平台单张的图片的大小不应大于 100KB。
  • 透明PNG图片可使用压缩工具压缩后提供。

    2.2 质量

  • 上线的图片都应该经过压缩处理,压缩后的图片不应该出现肉眼可感知的失真区域。

  • 60质量的JPEG格式图片与质量大于60的相比,肉眼已看不出明显的区别,因此保存 JPEG 图的时候,质量一般控制在60,若保真度要求高的图片可适量提高到 80,图片大小控制在 200KB 以内。
  • JPG图片必须压缩,一般80%品质即可,保证文字清晰。
  • JPG图片必须使用渐进式图片:使用Photoshop的“存储为Web所用格式”时候,勾选“连续”。

    2.3 跨域

    图片跨域问题的解决:设置图片 crossOrigin 属性为 ”Anonymous“。

    三、多媒体

    3.1 输出

  • 音频格式为.mp3。

  • 音频文件大小压缩控制在 1M 以内。

    3.2 自动播放

    背景音乐不能自动播放,音频在H5页面中通常做为背景音乐,有些需求要求实现自动播放,解决方法:

  • 页面设计中添加播放音乐的开关,通过交互操作实现音乐的播放;

  • 微信或APP场景中通过监听WeixinJSBridgeReady事件、DOMContentLoaded事件;
  • 通过手势事件播放音乐,监听body的touchstart事件,回调中播放音乐;
    参考《移动端H5页面音频/视频规范

    四、CSS

    4.1 分类

  • 重置(reset)和默认(base)(tags):消除默认样式和浏览器差异,并设置部分标签的初始样式,以减少后面的重复劳动。

  • 统一处理:建议在这个位置统一调用背景图(这里指多个布局或模块或元件共用的图)和清除浮动(这里指通用性较高的布局、模块、元件内的清除)等统一设置处理的样式。
  • 布局(grid)(.g-):将页面分割为几个大块,通常有头部、主体、主栏、侧栏、尾部等。
  • 模块(module)(.m-):通常是一个语义化的可以重复使用的较大的整体!比如导航、登录、注册、各种列表、评论、搜索等。
  • 元件(unit)(.u-):通常是一个不可再分的较为小巧的个体,通常被重复用于各种模块中!比如按钮、输入框、loading、图标等。
  • 功能(function)(.f-):为方便一些常用样式的使用,我们将这些使用率较高的样式剥离出来,按需使用,通常这些选择器具有固定样式表现,比如清除浮动等。
  • 皮肤(skin)(.s-):如果你需要把皮肤型的样式抽离出来,通常为文字色、背景色(图)、边框色等,非换肤型网站通常只提取文字色。
  • 状态(.z-):为状态类样式加入前缀,统一标识,方便识别,她只能组合使用或作为后代出现(.u-ipt.z-dis{},.m-list li.z-sel{})。

    4.2 命名规则

    ClassName的命名以上面的前缀开头,且全部字母为小写,单词之间统一使用横杠 “-” 连接。
    若这六类前缀不能满足需求,则可以另外定义一个或多个大类,但必须符合单个字母+”-“为前缀的命名规则,即 .x- 的格式。
    这么设计可让同样的 ClassName 在不同的模块或元件中重复使用,互不干扰;在多人协作或者分模块协作的时候效果尤为明显。
    命名也可参考《tailwind.css》。

    五、Node.js

    5.1 MySQL

    数据库在设计表的字段时,除了显而易见的字段(例如 cdate、mdate等),其余都必须配有注释,包括表的作用。
    当字段的值为常量时,应将其各个常量所对应的含义,也书写在备注中。

    六、工程师规范

    6.1 自测联调

  • 对自己的代码进行全面的多设备测试和兼容性测试。

  • 如果自测过程中发现别人写的代码有问题,及时反馈。

    6.2 总结分享

  • 分享内容可以包含:架构思想、协作心得、设备特性介绍、新技术应用、调研展示、遇到的问题和解决方案等。

  • 分享对象不限于:交互、视觉、前端及所有感兴趣的人。

    6.3 变更维护

  • 如果未经过需求变更和设计变更,原则上不允许直接进行开发变更。

  • 变更前应了解变更原因,变更后应该及时通知相关人员。

参考:
Aotu.io 前端代码规范
腾讯页面规范
Airbnb JavaScript 风格指南
百度编码规范
网易规范
JavaScript 代码规范
Vue.js 风格指南
ES6 编码风格
Bootstrap Code Style