Group items tagged

语义

版本控制

正确地拼写一个单词是底线

认真地注意 IDE 的 typo 提示（单词拼写错误提示）

state 是整个 Component 状态机中的某一个特定状态，既然描述为了状态机，那么状态和状态之间是互相切换的关系。所以对于初始状态，用 initial 来修饰。

props 是指 Element 的属性，要么是不存在某个属性值后来为它赋值，要么是存在属性的默认值后来将其覆盖。所以这种行为，default 是合理的修饰词。

成对出现的词应该是：show & hide、open & close。

成对出现的正反义词不可混用

在复数的风格上保持一致，要么所有都是 -s，要么所有都是 -list。

涉及到诸如字典（Dictionary）、表（Map）的时候，不要使用复数！

「map」本身已经包含了这层意思，不需要再用复数去修饰它

最好遵从惯例，使用名词组合 success 和 failure

方法命名用动词

属性命名用名词

布尔值类型用形容词

首字母缩写词的所有字母均大写。（如果某个语言环境有明确的业界惯例，则遵循惯例。）

如果什么都没定，也没业界惯例，那么把单词写全了总是不会错的。

React 采用了 componentDidMount 这种过去时风格，而没有使用 componentMounted，从而跟 componentWillMount 形成对照组，方便记忆。

尽量避免使用被动语态。因为被动语态看起来会比较绕，不够直观，因此我们要将被动语态的 API 转换为主动语态。

在文件（file）层面同样如此，一个文件只编写一个类，保证文件的职责单一（当然这对很多语言来说是天然的规则）。

将混杂在一个大坨函数中的两件独立事情拆分出去，保证函数（function）级别的职责单一。

现实中的 OOP 编程场景难免触及副作用。

函数本身的运行稳定可预期

函数的运行不对外部环境造成意料外的污染

SPM 是阿里通用的埋点统计方案

对外部造成污染一般是两种途径：一是在函数体内部直接修改外部作用域的变量，甚至全局变量；二是通过修改实参间接影响到外部环境，如果实参是引用类型的数据结构。

控制读写权限

可省略的参数后置，以及 为可省略的参数设定缺省值

将可省参数后置同样是最佳实践。

重载（overload）

如果入口参数无法进行有效区分，不要选择重载

根本不明白某个 Boolean 标记位是用来干嘛的，这大大降低了用户的开发体验，以及代码可读性。

同时支持单个和批量的处理，可以降低用户的认知负担。

让 setter 型 API 始终返回 this。这是 jQuery 为我们带来的经典启示 —— 通过返回 this，来产生一种「链式调用（chaining）」的风格

对异步操作都返回一个 Promise

对于一些创造出来的、业务特色的词汇，如果不能用英语简明地翻译，就直接用拼音

一致性可以最大程度降低信息熵

打 log 要么都用中文，要么都用英文。

所有的 setter 操作必须返回 this

「大版本号」即「语义化版本命名」<major>.<minor>.<patch> 中的第一位 <major> 位

接口的扩展方式有很多，比如：继承（extend）、组合（mixin）、装饰（decorate）

在逻辑上确实存在派生关系，并且需要沿用基类行为同时自定义行为的，采用重量级的继承

仅仅是扩充一些行为功能，但是逻辑上压根不存在父子关系的，使用组合

装饰手法更多应用于给定一个接口，将其包装成多种适用于不同场景新接口的情况

合理的做法是新增一个 subType 字段

抽象级别一般来说越高越好，将 API 设计成业务无关的，更通用，而且方便扩展

利用多态性（Polymorphism）构建 Consistent APIs。

作为 API 的开发者，一定要提供足够场景适用的 API，来引导我们的用户，不要让他们做出一些出人意料的「妙用」之举

写代码，就像写作，而设计 API 好比列提纲。