命名规约

命名规约

译自Naming cheatsheet

命名很难。本文试图使其变得更容易。
尽管这些建议可以应用于任何编程语言，但我将在实践中使用JavaScript进行说明。

英语

命名变量和函数时，请使用英语。

/* Bad */
const primerNombre = 'Gustavo'
const amigos = ['Kate', 'John']

/* Good */
const firstName = 'Gustavo'
const friends = ['Kate', 'John']

不论你喜不喜欢，英语是编程中的主要语言：所有编程语言的语法都是用英语写的，还有无数的文档和教材。通过用英语编写代码，可以大大提高其内聚性。

命名约定

选择一种命名约定并遵循它。只要保持一致，就可以是camelCase（小驼峰），PascalCase（大驼峰），snake_case（下划线）或其他约定形式。许多编程语言在命名约定方面都有自己的传统。查看您所用语言的文档或在Github上学习一些流行的存储库！

/* Bad */
const page_count = 5
const shouldUpdate = true

/* Good */
const pageCount = 5
const shouldUpdate = true

/* Good as well */
const page_count = 5
const should_update = true

S-I-D

名称必须short（简短），intuitive（直观）且具有descriptive（描述性）：

• Short. 名称应当简短，这样容易记；
• Intuitive. 名称应当自然易读，接地气；
• Descriptive. 名称必须以最有效的方式反映其功能。

/* Bad */
const a = 5 // "a" could mean anything
const isPaginatable = a > 10 // "Paginatable" sounds extremely unnatural
const shouldPaginatize = a > 10 // Made up verbs are so much fun!

/* Good */
const postCount = 5
const hasPagination = postCount > 10
const shouldPaginate = postCount > 10 // alternatively

避免缩写

不要使用缩写。它们只会降低代码的可读性。寻找简短的描述性名称可能很困难，但缩写不是这样做的借口。

/* Bad */
const onItmClk = () => {}

/* Good */
const onItemClick = () => {}

避免上下文重复

名称不应与定义名称的上下文重复。在不降低名称的可读性情况下，请务必从名称中删除该上下文重复名称。

class MenuItem {
  /* Method name duplicates the context (which is "MenuItem") */
  handleMenuItemClick = (event) => { ... }

  /* Reads nicely as `MenuItem.handleClick()` */
  handleClick = (event) => { ... }
}

反映预期结果

名称应反映预期的结果。

/* Bad */
const isEnabled = itemCount > 3
return <Button disabled={!isEnabled} />

/* Good */
const isDisabled = itemCount <= 3
return <Button disabled={isDisabled} />

函数命名

A/HC/LC 模式

在命名函数时，有一个有用的模式可以遵循：

prefix? + action (A) + high context (HC) + low context? (LC)

看看下表中如何应用此模式。

Name	Prefix	Action (A)	High context (HC)	Low context (LC)
getUser		get	User
getUserMessages		get	User	Messages
handleClickOutside		handle	Click	Outside
shouldDisplayMessage	should	Display	Message

注意：上下文的顺序会影响变量的含义。例如，shouldUpdateComponent意思你将要更新一个组件，shouldComponentUpdate意思组件自己更新，而你只能控制何时让其自动更新。换句话说，High context (HC)强调变量的含义。

Actions

函数名称的动词部分。负责描述功能的最重要部分。

get

立即访问数据（即内部数据的简写getter）。

function getFruitCount() {
  return this.fruits.length
}

参见compose

set

以声明方式设置变量，将值A设置为值B。

let fruits = 0

function setFruits(nextFruits) {
  fruits = nextFruits
}

setFruits(5)
console.log(fruits) // 5

reset

将变量设置回其初始值或状态。

const initialFruits = 5
let fruits = initialFruits
setFruits(10)
console.log(fruits) // 10

function resetFruits() {
  fruits = initialFruits
}

resetFruits()
console.log(fruits) // 5

fetch

请求一些数据，这需要花费不确定的时间（即异步请求）。

function fetchPosts(postCount) {
  return fetch('https://api.dev/posts', {...})
}

remove

从某处删除某物。

例如，如果您在搜索页面上有一个选定过滤器的集合，那么从集合中删除其中一个就是removeFilter，而不是deleteFilter（这也是您自然会用英语说的一种方式）：

function removeFilter(filterName, filters) {
  return filters.filter((name) => name !== filterName)
}

const selectedFilters = ['price', 'availability', 'size']
removeFilter('price', selectedFilters)

参见delete

delete

彻底从存在的领域中抹去一些东西。

假设您是内容编辑器，并且有一个臭名昭著的帖子希望您删除。单击闪亮的“删除帖子”按钮后，CMS将执行deletePost，而不是removePost。

function deletePost(id) {
  return database.find({ id }).delete()
}

参见remove

compose

从现有数据创建新数据。通常适用于字符串，对象或函数。

function composePageUrl(pageName, pageId) {
  return (pageName.toLowerCase() + '-' + pageId)
}

参见get

handle

处理一个动作。通常在命名回调方法时使用。

function handleLinkClick() {
  console.log('Clicked a link!')
}

link.addEventListener('click', handleLinkClick)

Context

函数操作的领域（上下文）。

函数通常是对某物的操作。重要的是要说明其可操作领域是什么，或至少是预期的数据类型。

/* A pure function operating with primitives */
function filter(list, predicate) {
  return list.filter(predicate)
}

/* Function operating exactly on posts */
function getRecentPosts(posts) {
  return filter(posts, (post) => post.date === Date.now())
}

某些特定的语言假设可能允许省略上下文。例如，在Java Script中，过filter通常操作Array。添加显式filterArray将是不必要的。

Prefixes

前缀增强了变量的含义。在函数名称中很少使用它。

is

描述当前上下文的特征或状态（通常为布尔值）。

const color = 'blue'
const isBlue = color === 'blue' // characteristic
const isPresent = true // state

if (isBlue && isPresent) {
  console.log('Blue is present!')
}

has

描述当前上下文是否具有某个值或状态（通常为布尔值）。

/* Bad */
const isProductsExist = productsCount > 0
const areProductsPresent = productsCount > 0

/* Good */
const hasProducts = productsCount > 0

should

反映一个肯定的条件语句（通常为布尔值），并加上特定的操作。

function shouldUpdateUrl(url, expectedUrl) {
  return url !== expectedUrl
}

min/max

表示最小值或最大值。在描述边界或界限时使用。

/**
 * Renders a random amount of posts within
 * the given min/max boundaries.
 */
function renderPosts(posts, minPosts, maxPosts) {
  return posts.slice(0, randomBetween(minPosts, maxPosts))
}

prev/next

指示当前上下文中变量的上一个或下一个状态。在描述状态转换时使用。

function fetchPosts() {
  const prevPosts = this.state.posts

  const fetchedPosts = fetch('...')
  const nextPosts = concat(prevPosts, fetchedPosts)

  this.setState({ posts: nextPosts })
}

单复数

像前缀一样，变量名可以保留为单个值或多个值，而可以单数形式或复数形式。

/* Bad */
const friends = 'Bob'
const friend = ['Bob', 'Tony', 'Tanya']

/* Good */
const friend = 'Bob'
const friends = ['Bob', 'Tony', 'Tanya']