转转前端开发规范的落地实践

正文

请到「今天看啥」查看全文

注释的原则

• 如无必要，勿增注释，应当追求「代码自注释」

// bad
// 如果已经准备好数据，就渲染表格
if (data.success && data.result.length > 0) {
  renderTable(data);
}

// good
const isTableDataReady = data.success && data.result.length > 0;
if (isTableDataReady) {
  renderTable(data);
}
复制代码

• 如有必要，尽量详尽，需要注释的地方应该尽量详尽地去写

注释的规范

遵循统一的风格规范，如一定的空格、空行，以保证注释自身的可读性

• 单行注释使用 // ，

注释行的上方需要有一个空行；注释内容和注释符之间需要有一个空格

function getType() {
  console.log('fetching type...');

  // set the default type to 'no type'
  const type = this.type || 'no type';
  return type;
}
复制代码

• 多行注释使用 /** ... */

/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make(tag) {
  // ...

  return element;
}
复制代码

• 使用特殊标记注释：如 TODO、FIXME、HACK 等

// TODO: 这里还需要做什么

// FIXME: 这里的实现有问题，以后需要优化

// HACK: 这里的处理是为了兼容低端安卓机的 bug
复制代码

• 文档类注释，如函数、类、文件、事件等，使用 jsdoc 规范

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

• 避免 情绪性注释：如抱怨、歧视、搞怪

/**
 * 穷逼VIP（活动送的那种）
 * @param update
 * @return {boolean}
 */
复制代码

浏览器兼容规范

团队应该根据的用户设备占比情况、应用类型、开发成本、浏览器市场统计数据等因素，来制定自己的浏览器兼容规范，转转的设备兼容规范如下

总体的机型兼用要求

安卓需要兼容安卓 4.0 以上， iOS 需要兼容 8.0 以上

# .browserlistrc
> 1%
last 3 versions
iOS >= 8
Android >= 4
Chrome >= 40
复制代码

CSS 的兼容要求

在 CSS 的兼容处理上，我们使用的是 postcss 的 autoprefixer

// postcss.config.js
module.exports = {
  plugins: {
    autoprefixer: {},
    cssnano: {
      autoprefixer: false,
      zindex: false,
      discardComments: {
        removeAll: true
      },
      reduceIdents: false
    }
  }
}
复制代码

js 的兼容要求

在处理 js 的兼容性时，我们使用 babel 抹平浏览器差异。

需要注意的是 proxy 是无法被降级处理的。需要慎重使用。

• 业务项目中，通过配置 @babel/preset-env 的 useBuiltIns: 'entry', corejs: 3 ，来根据 .browserslistrc 引入 polyfill

// babel.config.js
module.exports = {
  presets: [
    ['@vue/app', {
      useBuiltIns: 'entry'
    }]
  ]
}
复制代码

// main.js
import 'core-js/stable'
import 'regenerator-runtime/runtime'
复制代码

以 Vue 项目为例， @vue/babel-preset-app 的配置会透传至 @babel/preset-env ，并默认使用 core-js@3

• 基础库中，通过配置 @babel/preset-env 的 useBuiltIns: 'usage', corejs: 3 来处理 js 兼容问题，减少项目体积

// babel.config.js
module.exports = {
  presets: [
    ['@babel/env', {
      useBuiltIns: 'usage',
      corejs: 3
    }]
  ],
  plugins: [
    ['@babel/transform-runtime'],
  ]
}
复制代码

HTTP 缓存规范

转转的绝大多数项目都是单页应用，根据项目特点我们设置了如下的缓存规范

静态资源

静态资源域名 s1.zhuanstatic.com ，是通过 cache-control 来做强制缓存，缓存时间是 30 天

cache-control: max-age=2592000
复制代码

html文件

域名 m.zhuanzhuan.com 下的 html 文件，是通过 Etag 来做协商缓存

etag: W/"5dfb384c-4cd"
复制代码

压缩

所有的资源都已开启的 gzip 压缩

通讯协议

默认使用的通信协议是 http2

编辑器规范

使用 Editorconfig 用来帮助你规范编辑器的的配置

Editorconfig 具体配置

配置文件 .editorconfig

root = true

[*]
indent_style = space                    # 输入的 tab 都用空格代替

请到「今天看啥」查看全文