前端代码规范汇总

前言

本文部分内容基于 Vue，大部分情况下都是前端通用的。
本文旨在规范lint不能解决的前端代码，不与已有的 eslint、 stylelint、prettier 规则重复。

规范

HTML规范

语义化标签

• 标题 h1 ~ h5
• 列表 ul + li
• 文字块 p

• 布局

  • header
  • nav
  • section
  • article
  • aside
  • footer
  • 
• 以上都不适用的情况下，再考虑 块级 div + 行内 span

自定义标签

参考 Vue风格指南。

import CEmpty from '@/components/CEmpty.vue';

<!-- 无属性 -->
<CEmpty />

<!-- 多属性 -->
<CEmpty
  :description=""
  :image=""
/>

<!-- 插槽 -->
<CEmpty
  :description=""
  :image=""
>
  暂无数据
</CEmpty>

CSS规范

推荐

• scoped 标签

• BEM 命名

  .x-page {
    .x-list {
      &-item {
        &__value {}
      }
    }
  }

避免

• !important 选择器
• style="" 行内样式
• 嵌套过多

命名规范

目录

• 文件夹 kebab-case
• .vue文件 PascalCase

• 非.vue文件 kebab-case

  |-- components
  | |-- c-table
  | | | -- c-table.js
  | | | -- CTable.vue

template

component

<!-- MultiWord -->
<CEmpty />

class

基于 BEM， tailwindcss 可忽略。

• 页面 x-page
• 包裹 x-wrapper
• 区块 x-wrapper-block
• 表单 x-wrapper-form
• 卡片 x-wrapper-card
• 列表 x-wrapper-list
• 列表项 x-wrapper-list-item

• 元素

  • x-wrapper-list-item__label
  • x-wrapper-list-item__value
  • x-wrapper-list-item__desc

• 状态

  • x-wrapper-list-item__checkbox--checked
  • x-wrapper-list-item__checkbox--disabled

• 主题色

  • x-wrapper-list-item__title--primary
  • x-wrapper-list-item__title--success
  • x-wrapper-list-item__title--warning
  • x-wrapper-list-item__title--danger

• 位置

  • x-wrapper-list-item--left
  • x-wrapper-list-item--right
  • x-wrapper-list-item--center
  • x-wrapper-list-item--top
  • x-wrapper-list-item--bottom
  • x-wrapper-list-item--middle

script

• 常量 SCREAMING_SNAKE_CASE

  const PI = 3.1415;
  const MAX_VALUE = Number.MAX_VALUE;

• 变量 camelCase

  const isLoading = false;
  const canEdit = false;
  const hasAuth = false;

• 函数 camelCase

  • get / set / fetch
  • show / hide / toggle
  • add / remove
  • view / create / edit / save / delete

  const getTableData = () => {};
  const showModal = () => {};

• 构造函数 PascalCase
• 类 PascalCase
• 类型定义 PascalCase

• 枚举 PascalCase

  • 枚举属性 SCREAMING_SNAKE_CASE

  const enum Action {
    CREATE = 'CREATE',
    EDIT = 'EDIT',
  }

注释规范

template

<!-- 单行注释 -->

<!--
  多行注释
  多行注释
-->

<!-- 元素块注释 start -->
H<sub>2</sub>O
x<sup>2</sup> = x * x
<!-- 元素块注释 end -->

script

• 普通注释

  // comment
  const num = 1;

• 代码块注释

  /* comment start */
  const num = 1;
  const str = 'bear';
  /* comment end */

• JSDoc注释

  /**
   * 类名/函数名
   * @author bear 
   * @param 参数
   * @return 无 
   */
  const foo = () => {};

  对于类、函数、枚举等来说，可以做到代码即文档。
  
  

特殊标记

• todo 提示有待完成的功能
• fixme 预留代码位置，待小伙伴协助开发
• hack 临时解决方案或不够优雅的代码

• deprecated 表示代码已废弃，将在未来某个版本删除

  // todo 增加xx功能
  
  // fixme @xxx 详情页地址待补充
  
  // hack 临时样式修复 待框架更新xx包版本后可删除
  
  // deprecated 推荐使用AbortController替代CancelToken

Git规范

Git分支规范