【搬运】编程中命名的一些参考

简单用百度翻译了一些内容，没有全部翻译。
有不认识的用百度翻译 翻译一下看看吧 QAQ
原作者GitHub链接

Naming cheatsheet

• English language 用英文命名
• Naming convention 使用约定俗成的命名规则并从一而终
• S-I-D 用简单、直观、描述性的语言
• Avoid contractions 避免缩写
• Avoid context duplication 避免上下文重复
• Reflect the expected result 反映预期效果
• Naming functions对函数命名
  • A/HC/LC pattern实用句式
    • Actions动作
    • Context内容
    • Prefixes 前缀
• Singular and Plurals 单复数

---

Naming things is hard. This sheet attempts to make it easier.

编程中命名是一件困难的事情 这份表的目的是让命名变得简单起来

Although these suggestions can be applied to any programming language, I will use JavaScript to illustrate them in practice.

以下命名建议可以应用到任何编程语言上，在这里使用JavaScript语言来作为说明

English language

Use English language when naming your variables and functions.

用英语来进行命名

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

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

Like it or not, English is the dominant language in programming: the syntax of all programming languages is written in English, as well as countless documentations and educational materials. By writing your code in English you dramatically increase its cohesiveness.

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

Naming convention

Pick one naming convention and follow it. It may be camelCase, PascalCase, snake_case, or anything else, as long as it remains consistent. Many programming languages have their own traditions regarding naming conventions; check the documentation for your language or study some popular repositories on Github!

选择一命名约定并遵循它。它可以是“camelCase”、“PascalCase”、“snake\u 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

A name must be short, intuitive and descriptive:

名称必须是简短的、直观的和描述性的：

• Short. A name must not take long to type and, therefore, remember;
• Intuitive. A name must read naturally, as close to the common speech as possible;
• Descriptive. A name must reflect what it does/possesses in the most efficient way.

/* 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

Avoid contractions

避免缩写

Do not use contractions. They contribute to nothing but decreased readability of the code. Finding a short, descriptive name may be hard, but contraction is not an excuse for not doing so.

避免缩略语不要使用缩略语。它们只会降低代码的可读性。找到一个简短的，描述性的名字可能很难，但缩写不是不这样做的借口。

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

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

Avoid context duplication

避免上下文重复

A name should not duplicate the context in which it is defined. Always remove the context from a name if that doesn’t decrease its readability.

名称不应与定义它的上下文重复。如果不降低名称的可读性，请始终从名称中删除上下文。

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

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

Reflect the expected result

反映预期结果

A name should reflect the expected result.

名称应反映预期结果。

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

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

---

Naming functions

A/HC/LC Pattern

There is a useful pattern to follow when naming functions:

命名函数时有一个实用的句式：

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

Take a look at how this pattern may be applied in the table below.

让我们看看下表中如何应用此句式。

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

Note: The order of context affects the meaning of a variable. For example, shouldUpdateComponent means you are about to update a component, while shouldComponentUpdate tells you that component will update on itself, and you are but controlling when it should be updated.
In other words, high context emphasizes the meaning of a variable.

**注：**上下文顺序影响变量的含义。例如，shouldcomponentupdatecomponent表示您将要更新一个组件，而shouldComponentUpdate则告诉您组件将在自身上更新，您只能控制何时应该更新它。
换句话说，高语境强调变量的含义。

---

Actions

The verb part of your function name. The most important part responsible for describing what the function does.

函数名的动词部分。最重要的部分是描述函数的作用。

get

Accesses data immediately (i.e. shorthand getter of internal data).

以声明方式设置变量，将值“a”设置为值“B”。

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

See also compose.

set

Sets a variable in a declarative way, with value A to value B.

let fruits = 0

function setFruits(nextFruits) {
  fruits = nextFruits
}

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

reset

Sets a variable back to its initial value or state.

将变量设置回其初始值或状态。（复位）

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

function resetFruits() {
  fruits = initialFruits
}

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

fetch

Request for some data, which takes some indeterminate time (i.e. async request).

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

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

remove

Removes something from somewhere.

For example, if you have a collection of selected filters on a search page, removing one of them from the collection is removeFilter, not deleteFilter (and this is how you would naturally say it in English as well):

从某处移除某物。
例如，如果您在搜索页上有一个选定筛选器的集合，则从集合中删除其中一个筛选器的方法是“removeFilter”，而不是“deleteFilter”（这也是您用英语自然表达的方式）：

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

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

See also delete.

delete

Completely erases something from the realms of existence.

Imagine you are a content editor, and there is that notorious post you wish to get rid of. Once you clicked a shiny “Delete post” button, the CMS performed a deletePost action, not removePost.

完全从存在的领域中抹去某些东西。
假设你是一个内容编辑，有一个臭名昭著的职位，你想摆脱。一旦你点击一个闪亮的“deletePost”按钮，CMS就会执行一个“deletePost”操作，而不是“removePost”。

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

See also remove.

compose

Creates new data from the existing one. Mostly applicable to strings, objects, or functions.

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

See also get.

handle

Handles an action. Often used when naming a callback method.

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

link.addEventListener('click', handleLinkClick)

---

Context

A domain that a function operates on.

A function is often an action on something. It is important to state what its operable domain is, or at least an expected data type.

/* 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())
}

Some language-specific assumptions may allow omitting the context. For example, in JavaScript, it’s common that filter operates on Array. Adding explicit filterArray would be unnecessary.

–

Prefixes

Prefix enhances the meaning of a variable. It is rarely used in function names.

前缀增强了变量的含义。它很少用于函数名。

is

Describes a characteristic or state of the current context (usually boolean).

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

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

has

Describes whether the current context possesses a certain value or state (usually boolean).

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

/* Good */
const hasProducts = productsCount > 0

should

Reflects a positive conditional statement (usually boolean) coupled with a certain action.

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

min/max

Represents a minimum or maximum value. Used when describing boundaries or limits.

/**
 * 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

Indicate the previous or the next state of a variable in the current context. Used when describing state transitions.

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

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

  this.setState({ posts: nextPosts })
}

Singular and Plurals

Like a prefix, variable names can be made singular or plural depending on whether they hold a single value or multiple values.

与前缀一样，变量名可以是单数的，也可以是复数的，这取决于它们是包含一个值还是多个值。

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

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