前言

本文部分內容基於 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分支規範