組員重構程式碼千奇百怪，直接JS、ES6和Vue規範給一梭子

wuwhs發表於2022-02-22
JSVue

前言

近期組員接手了一個“古老“的初始由後端大佬寫的前端專案，業務層面的元件複用，全靠是 copy 相同程式碼我們不說，經過不同大佬們的維護，程式碼風格更是千奇百怪。該前端專案還在正常迭代更新，又不可能重寫，面對 ? 一樣的程式碼，兩個接手的小前端抱著欲哭無淚，瑟瑟發抖。見狀，只能安慰之，暫時發揮啊 Q 精神，規範自己的新程式碼，然後每次迭代開發任務重構一兩個舊元件，此過程持續 2-3 個月後，上 eslint 和 prettier 自動化檢測語法和格式化程式碼。
本著“程式碼不規範，新人兩行淚”的警示，總結出如下 JavaScrip、ES6 和 Vue 單檔案元件相關程式碼風格案例，供大家參考。

Javascript 程式碼風格

使用有意義的變數名稱

變數的名稱應該是可描述，有意義的， JavaScript 變數都應該採用駝峰式大小寫 ( camelCase) 命名。

// bad ❌
const foo = 'JDoe@example.com'
const bar = 'John'
const age = 23
const qux = true

// good ✅
const email = 'John@example.com'
const firstName = 'John'
const age = 23
const isActive = true

布林變數通常需要回答特定問題，例如：

isActive
didSubscribe
hasLinkedAccount

避免新增不必要的上下文

當物件或類已經包含了上下文的命名時，不要再向變數名稱新增冗餘的上下文。

// bad ❌
const user = {
  userId: '296e2589-7b33-400a-b762-007b730c8e6d',
  userEmail: 'JDoe@example.com',
  userFirstName: 'John',
  userLastName: 'Doe',
  userAge: 23
}

user.userId

//good ✅
const user = {
  id: '296e2589-7b33-400a-b762-007b730c8e6d',
  email: 'JDoe@example.com',
  firstName: 'John',
  lastName: 'Doe',
  age: 23
}

user.id

避免硬編碼值

// bad ❌
setTimeout(clearSessionData, 900000)

//good ✅
const SESSION_DURATION_MS = 15 * 60 * 1000

setTimeout(clearSessionData, SESSION_DURATION_MS)

使用有意義的函式名稱

函式名稱需要描述函式的實際作用，即使很長也沒關係。函式名稱通常使用動詞，但返回布林值的函式可能是個例外 — 它可以採用 是或否 問題的形式，函式名也應該是駝峰式的。

// bad ❌
function toggle() {
  // ...
}

function agreed(user) {
  // ...
}

//good ✅
function toggleThemeSwitcher() {
  // ...
}

function didAgreeToAllTerms(user) {
  // ...
}

限制引數的數量

儘管這條規則可能有爭議，但函式最好是有 3 個以下引數。如果引數較多可能是以下兩種情況之一：

  • 該函式做的事情太多，應該拆分。
  • 傳遞給函式的資料以某種方式相關，可以作為專用資料結構傳遞。
// bad ❌
function sendPushNotification(title, message, image, isSilent, delayMs) {
  // ...
}

sendPushNotification('New Message', '...', 'http://...', false, 1000)

//good ✅
function sendPushNotification({ title, message, image, isSilent, delayMs }) {
  // ...
}

const notificationConfig = {
  title: 'New Message',
  message: '...',
  image: 'http://...',
  isSilent: false,
  delayMs: 1000
}

sendPushNotification(notificationConfig)

避免在一個函式中做太多事情

一個函式應該一次做一件事，這有助於減少函式的大小和複雜性，使測試、除錯和重構更容易。

// bad ❌
function pingUsers(users) {
  users.forEach((user) => {
    const userRecord = database.lookup(user)
    if (!userRecord.isActive()) {
      ping(user)
    }
  })
}

//good ✅
function pingInactiveUsers(users) {
  users.filter(!isUserActive).forEach(ping)
}

function isUserActive(user) {
  const userRecord = database.lookup(user)
  return userRecord.isActive()
}

避免使用布林標誌作為引數

函式含有布林標誌的引數意味這個函式是可以被簡化的。

// bad ❌
function createFile(name, isPublic) {
  if (isPublic) {
    fs.create(`./public/${name}`)
  } else {
    fs.create(name)
  }
}

//good ✅
function createFile(name) {
  fs.create(name)
}

function createPublicFile(name) {
  createFile(`./public/${name}`)
}

避免寫重複的程式碼

如果你寫了重複的程式碼，每次有邏輯改變，你都需要改動多個位置。

// bad ❌
function renderCarsList(cars) {
  cars.forEach((car) => {
    const price = car.getPrice()
    const make = car.getMake()
    const brand = car.getBrand()
    const nbOfDoors = car.getNbOfDoors()

    render({ price, make, brand, nbOfDoors })
  })
}

function renderMotorcyclesList(motorcycles) {
  motorcycles.forEach((motorcycle) => {
    const price = motorcycle.getPrice()
    const make = motorcycle.getMake()
    const brand = motorcycle.getBrand()
    const seatHeight = motorcycle.getSeatHeight()

    render({ price, make, brand, nbOfDoors })
  })
}

//good ✅
function renderVehiclesList(vehicles) {
  vehicles.forEach((vehicle) => {
    const price = vehicle.getPrice()
    const make = vehicle.getMake()
    const brand = vehicle.getBrand()

    const data = { price, make, brand }

    switch (vehicle.type) {
      case 'car':
        data.nbOfDoors = vehicle.getNbOfDoors()
        break
      case 'motorcycle':
        data.seatHeight = vehicle.getSeatHeight()
        break
    }

    render(data)
  })
}

避免副作用

在 JavaScript 中，你應該更喜歡函式式模式而不是命令式模式。換句話說，大多數情況下我們都應該保持函式純潔。副作用可能會修改共享狀態和資源，從而導致一些奇怪的問題。所有的副作用都應該集中管理，例如你需要更改全域性變數或修改檔案，可以專門寫一個 util 來做這件事。

// bad ❌
let date = '21-8-2021'

function splitIntoDayMonthYear() {
  date = date.split('-')
}

splitIntoDayMonthYear()

// Another function could be expecting date as a string
console.log(date) // ['21', '8', '2021'];

//good ✅
function splitIntoDayMonthYear(date) {
  return date.split('-')
}

const date = '21-8-2021'
const newDate = splitIntoDayMonthYear(date)

// Original vlaue is intact
console.log(date) // '21-8-2021';
console.log(newDate) // ['21', '8', '2021'];

另外，如果你將一個可變值傳遞給函式，你應該直接克隆一個新值返回，而不是直接改變該它。

// bad ❌
function enrollStudentInCourse(course, student) {
  course.push({ student, enrollmentDate: Date.now() })
}

//good ✅
function enrollStudentInCourse(course, student) {
  return [...course, { student, enrollmentDate: Date.now() }]
}

使用非負條件

// bad ❌
function isUserNotVerified(user) {
  // ...
}

if (!isUserNotVerified(user)) {
  // ...
}

//good ✅
function isUserVerified(user) {
  // ...
}

if (isUserVerified(user)) {
  // ...
}

儘可能使用簡寫

// bad ❌
if (isActive === true) {
  // ...
}

if (firstName !== '' && firstName !== null && firstName !== undefined) {
  // ...
}

const isUserEligible = user.isVerified() && user.didSubscribe() ? true : false

//good ✅
if (isActive) {
  // ...
}

if (!!firstName) {
  // ...
}

const isUserEligible = user.isVerified() && user.didSubscribe()

避免過多分支

儘早 return 會使你的程式碼線性化、更具可讀性且不那麼複雜。

// bad ❌
function addUserService(db, user) {
  if (!db) {
    if (!db.isConnected()) {
      if (!user) {
        return db.insert('users', user)
      } else {
        throw new Error('No user')
      }
    } else {
      throw new Error('No database connection')
    }
  } else {
    throw new Error('No database')
  }
}

//good ✅
function addUserService(db, user) {
  if (!db) throw new Error('No database')
  if (!db.isConnected()) throw new Error('No database connection')
  if (!user) throw new Error('No user')

  return db.insert('users', user)
}

優先使用 map 而不是 switch 語句

既能減少複雜度又能提升效能。

// bad ❌
const getColorByStatus = (status) => {
  switch (status) {
    case 'success':
      return 'green'
    case 'failure':
      return 'red'
    case 'warning':
      return 'yellow'
    case 'loading':
    default:
      return 'blue'
  }
}

//good ✅
const statusColors = {
  success: 'green',
  failure: 'red',
  warning: 'yellow',
  loading: 'blue'
}

const getColorByStatus = (status) => statusColors[status] || 'blue'

使用可選連結

const user = {
  email: 'JDoe@example.com',
  billing: {
    iban: '...',
    swift: '...',
    address: {
      street: 'Some Street Name',
      state: 'CA'
    }
  }
}

// bad ❌
const email = (user && user.email) || 'N/A'
const street = (user && user.billing && user.billing.address && user.billing.address.street) || 'N/A'
const state = (user && user.billing && user.billing.address && user.billing.address.state) || 'N/A'

//good ✅
const email = user?.email ?? 'N/A'
const street = user?.billing?.address?.street ?? 'N/A'
const street = user?.billing?.address?.state ?? 'N/A'

避免回撥

回撥很混亂，會導致程式碼巢狀過深，使用 Promise 替代回撥。

// bad ❌
getUser(function (err, user) {
  getProfile(user, function (err, profile) {
    getAccount(profile, function (err, account) {
      getReports(account, function (err, reports) {
        sendStatistics(reports, function (err) {
          console.error(err)
        })
      })
    })
  })
})

//good ✅
getUser()
  .then(getProfile)
  .then(getAccount)
  .then(getReports)
  .then(sendStatistics)
  .catch((err) => console.error(err))

// or using Async/Await ✅✅

async function sendUserStatistics() {
  try {
    const user = await getUser()
    const profile = await getProfile(user)
    const account = await getAccount(profile)
    const reports = await getReports(account)
    return sendStatistics(reports)
  } catch (e) {
    console.error(err)
  }
}

處理丟擲的錯誤和 reject 的 promise

// bad ❌
try {
  // Possible erronous code
} catch (e) {
  console.log(e)
}

//good ✅
try {
  // Possible erronous code
} catch (e) {
  // Follow the most applicable (or all):
  // 1- More suitable than console.log
  console.error(e)

  // 2- Notify user if applicable
  alertUserOfError(e)

  // 3- Report to server
  reportErrorToServer(e)

  // 4- Use a custom error handler
  throw new CustomError(e)
}

只註釋業務邏輯

// bad ❌
function generateHash(str) {
  // Hash variable
  let hash = 0

  // Get the length of the string
  let length = str.length

  // If the string is empty return
  if (!length) {
    return hash
  }

  // Loop through every character in the string
  for (let i = 0; i < length; i++) {
    // Get character code.
    const char = str.charCodeAt(i)

    // Make the hash
    hash = (hash << 5) - hash + char

    // Convert to 32-bit integer
    hash &= hash
  }
}

// good ✅
function generateHash(str) {
  let hash = 0
  let length = str.length
  if (!length) {
    return hash
  }

  for (let i = 0; i < length; i++) {
    const char = str.charCodeAt(i)
    hash = (hash << 5) - hash + char
    hash = hash & hash // Convert to 32bit integer
  }
  return hash
}

ES6 優化原生 JS（ES5） 程式碼風格

使用預設引數

// bad ❌
function printAllFilesInDirectory(dir) {
  const directory = dir || './'
  //   ...
}

// good ✅
function printAllFilesInDirectory(dir = './') {
  // ...
}

物件結構取值

const obj = {
  a: 1,
  b: 2,
  c: 3,
  d: 4,
  e: 5
}

// bad ❌
const f = obj.a + obj.d
const g = obj.c + obj.e

// good ✅
const { a, b, c, d, e } = obj
const f = a + d
const g = c + e

ES6 的解構賦值雖然好用。但是要注意解構的物件不能為 undefined、null。否則會報錯，故要給被解構的物件一個預設值。

const { a, b, c, d, e } = obj || {}

擴充運算子合並資料

合併陣列或者物件，用 ES5 的寫法有些冗餘

const a = [1, 2, 3]
const b = [1, 5, 6]
const obj1 = {
  a: 1
}
const obj2 = {
  b: 1
}

// bad ❌
const c = a.concat(b) //[1,2,3,1,5,6]
const obj = Object.assign({}, obj1, obj2) // {a:1, b:1}

// good ✅
const c = [...new Set([...a, ...b])] //[1,2,3,5,6]
const obj = { ...obj1, ...obj2 } // {a:1, b:1}

拼接字元

const name = '小明'
const score = 59

// bad ❌
let result = ''
if (score > 60) {
  result = `${name}的考試成績及格`
} else {
  result = `${name}的考試成績不及格`
}

// good ✅
const result = `${name}${score > 60 ? '的考試成績及格' : '的考試成績不及格'}`

includes 替代多條件判斷

// bad ❌
f(
    type == 1 ||
    type == 2 ||
    type == 3 ||
    type == 4 ||
){
   //...
}

// good ✅
const condition = [1,2,3,4];

if( condition.includes(type) ){
   //...
}

列表查詢某一項

const a = [1, 2, 3, 4, 5]

// bad ❌
const result = a.filter((item) => {
  return item === 3
})

// good ✅
const result = a.find((item) => {
  return item === 3
})

陣列扁平化

// bad ❌
const deps = {
  採購部: [1, 2, 3],
  人事部: [5, 8, 12],
  行政部: [5, 14, 79],
  運輸部: [3, 64, 105]
}
let member = []
for (let item in deps) {
  const value = deps[item]
  if (Array.isArray(value)) {
    member = [...member, ...value]
  }
}
member = [...new Set(member)]

// good ✅
const member = Object.values(deps).flat(Infinity)

可選鏈操作符獲取物件屬性值

// bad ❌
const name = obj && obj.name

// good ✅
const name = obj?.name

動態物件屬性名

// bad ❌
let obj = {}
let index = 1
let key = `topic${index}`
obj[key] = '話題內容'

// good ✅
obj[`topic${index}`] = '話題內容'

判斷非空

// bad ❌
if (value !== null && value !== undefined && value !== '') {
  //...
}

// good ✅
if ((value ?? '') !== '') {
  //...
}

Vue 元件風格

Vue 單檔案元件風格指南內容節選自 Vue 官方風格指南。

元件資料

元件的 data 必須是一個函式。

// bad
export default {
  data: {
    foo: 'bar'
  }
};

// good
export default {
  data() {
    return {
      foo: 'bar'
    };
  }
};

單檔案元件檔名稱

單檔案元件的檔名應該要麼始終是單詞大寫開頭 (PascalCase)，要麼始終是橫線連線 (kebab-case)。

// bad
mycomponent.vue
myComponent.vue

// good
my - component.vue
MyComponent.vue

緊密耦合的元件名

和父元件緊密耦合的子元件應該以父元件名作為字首命名。

// bad
components/
|- TodoList.vue
|- TodoItem.vue
└─ TodoButton.vue

// good
components/
|- TodoList.vue
|- TodoListItem.vue
└─ TodoListItemButton.vue

自閉合元件

在單檔案元件中沒有內容的元件應該是自閉合的。

<!-- bad -->
<my-component></my-component>

<!-- good -->
<my-component />

Prop 名大小寫

在宣告 prop 的時候，其命名應該始終使用 camelCase，而在模板中應該始終使用 kebab-case。

// bad
export default {
  props: {
    'greeting-text': String
  }
};

// good
export default {
  props: {
    greetingText: String
  }
};
<!-- bad -->
<welcome-message greetingText="hi" />

<!-- good -->
<welcome-message greeting-text="hi" />

指令縮寫

指令縮寫，用 : 表示 v-bind: ，用 @ 表示 v-on:

<!-- bad -->
<input v-bind:value="value" v-on:input="onInput" />

<!-- good -->
<input :value="value" @input="onInput" />

Props 順序

標籤的 Props 應該有統一的順序，依次為指令、屬性和事件。

<my-component
  v-if="if"
  v-show="show"
  v-model="value"
  ref="ref"
  :key="key"
  :text="text"
  @input="onInput"
  @change="onChange"
/>

元件選項的順序

元件選項應該有統一的順序。

export default {
  name: '',

  components: {},

  props: {},

  emits: [],

  setup() {},

  data() {},

  computed: {},

  watch: {},

  created() {},

  mounted() {},

  unmounted() {},

  methods: {}
}

元件選項中的空行

元件選項較多時，建議在屬性之間新增空行。

export default {
  computed: {
    formattedValue() {
      // ...
    },

    styles() {
      // ...
    }
  },

  methods: {
    onInput() {
      // ...
    },

    onChange() {
      // ...
    }
  }
}

單檔案元件頂級標籤的順序

單檔案元件應該總是讓頂級標籤的順序保持一致，且標籤之間留有空行。

<template> ... </template>

<script>
  /* ... */
</script>

<style>
  /* ... */
</style>

相關文章