核心是要清晰的表达意思,其次简洁
本文参考总结官方文档
清晰明了
1. 包含必要的单词
比如一个可以List移除element的方法,函数名要表达是移除某个未知的element还是移除某个element
// ✅
extension List {
public mutating func remove(at position: Index) -> Element
}
employees.remove(at: x)
// ❌
employees.remove(x) // 错误,不知道x是位置还是element
2. 省略不必要的词
如果某个词不包含也不影响读者阅读代码,那么这个词就该被省略
比如下面的removeElement中的element就是多余的
// ❌
public mutating func removeElement(_ member: Element) -> Element?
allViews.removeElement(cancelButton) // 冗余
// ✅
public mutating func remove(_ member: Element) -> Element?
allViews.remove(cancelButton) // 足够清晰
3. 根据语义而不是类型约束来命名
// ❌
var string = "Hello"
protocol ViewController {
associatedtype ViewType : View
}
class ProductionLine {
func restock(from widgetFactory: WidgetFactory)
}
// ✅
var greeting = "Hello"
protocol ViewController {
associatedtype ContentView : View
}
class ProductionLine {
func restock(from supplier: WidgetFactory)
}
4. 补偿弱类型信息以阐明参数的作用
比如当参数类型是any
,anyObject
或者Int
等基本类型的时候就不足够传达意思,需要加以解释
// ❌
func add(_ observer: NSObject, for keyPath: String)
grid.add(self, for: graphics) // 不清晰
// ✅
func addObserver(_ observer: NSObject, forKeyPath path: String)
grid.addObserver(self, forKeyPath: graphics) // 清除
语义流畅
1. 函数名字最好能符合自然语言表意
/// 语义流畅 ✅
x.insert(y, at: z) “x, insert y at z”
x.subViews(havingColor: y) “x's subviews having color y”
x.capitalizingNouns() “x, capitalizing nouns”
// 语义不流畅 ❌
x.insert(y, position: z)
x.subViews(color: y)
x.nounCapitalize()
如果第一个参数或第二个参数对于调用的意义不是中心意义,则流利性下降是可以接受的:
AudioUnit.instantiate(
with: description,
options: [.inProcess], completionHandler: stopProgressBar)
2. 工厂方法的名称以“ make” 开头, 例如x.makeIterator()。
3. 初始化程序和工厂方法调用的第一个参数不以语义流畅为目的
/// 这样简洁明了 ✅
let foreground = Color(red: 32, green: 64, blue: 128)
let newPart = factory.makeWidget(gears: 42, spindles: 14)
let ref = Link(target: destination)
// 不需要这样 ❌
let foreground = Color(havingRGBValuesRed: 32, green: 64, andBlue: 128)
let newPart = factory.makeWidget(havingGearCount: 42, andSpindleCount: 14)
let ref = Link(to: destination)
4. 明确函数副作用
比如mutating
的函数动词要从祈使语态的原型变成过去式或者正在进行时表示状态
|:-:|:-:|
|Nonmutating | Mutating|
|x.sort()| x.sorted() |
|x.append()| x.appending()|
术语
1. 避免晦涩难懂的不常用词
2. 如果使用晦涩的词,一定要准确达意
3. 避免缩写,除非是大家都知道的
4. 遵循先例
比如大多数程序里面都是用Array来表示数组、列表,如果没有其它目的就不要用List来表述,尽管List语义上没问题