用这些手法让你的代码更易读

(Updated: )

翻译于：Making your iOS application easy to read with these simple steps.

好的开发者能够竭尽他们所能去简单的描述他们的意图。就像物理学家会通过用一根铅笔插入一张对折的纸张来描述虫洞一样，简洁而直观。是什么让我们如此不同？

我经常尽我所能让我的代码更加易读，很多时候依据代码的约定为我们的变量选取一个合适的名字很有用，但是还有一些东西仍然时缺失的，我们缺乏一种编写代码的方式，让我们能够直接理解代码的意思而不是迷惑的尝试去理解这段代码为什么要这样？我正在尝试去实现它。

你可能会说这种能力就是**让代码读起来像是一个故事，而不是一堆单词**

接下来要介绍3个主要的规则

问题

阅读别人的代码真的是一件让人头大的事情。如果没有程序的上下文，我们很容易迷失在寻找函数或参数含义的途中，无法自拔。

建议

从二进制到低级语言再到高级语言，很容易意识到编码变的越来越友好了，因此有了更多的开发者加入程序员的世界里。就像编码方式正在变得更简洁易读，我们写代码也应该如此，简单的说，我们的代码要直中要义而切能自我解释。

结果

一个好的编码方法可以让我们的代码变得像一个故事一样，更加易读也更易被别人所理解。

方法命令

如何进行一个正确的命名：

当我们创建一个方法时，我们总是假设人们在读这个方法时是知道上下文的，知道我们想要达到什么样的效果。例如我们给方法一个模糊的命名handleRedView()会导致很多的问题出现，RedView代表的是什么东西？这个方法的主要目的是什么呢？

可以看出，在一些情况下，我们的方法功能可能太过模糊或太过复杂，我们很难来脱离上下文的情况下理解它的作用。

现在，我们要把所有的方法分为4个类别：

  • Informer functions
  • Management functions
  • Router functions
  • Execution functions

1. Informer function

经常用来触发 router/management functions

例如：

1
2
3
4
5
6
7
//dataHasUpdated.swift

delegate.dataHasUpdated()

func dataHasUpdated {
    //Someone is informing you that something has happed.
}
1
2
3
4
5
6
7
// viewDidLoad.swift

// Informer Functions
override func engineStarted() {
    super.engineStarted()
    handleCarStarted()
}

回调方法，通知一些方法调用或状态改变将要或正在发生，给你提供选择反应的机会。
多数情况下，是用来触发delgate方法，或是发送通知。

2. Management function

通常用来集合多个相互之间没有依赖的方法用来实现一个更高级的目的。代码块中所有的方法都会被调用。

1
2
3
4
5
6
// Management Function

func handleCarStarted() {
    trunLights(on: true)
    turnAC(on: true)
}

阅读这个方法，我们能够知道所有我们需要进行的操作， 执行这个方法汽车就会启动， 在这一个时刻，我们只关心调用的方法是什么意思，而不用管他们时如何实现的。

3. Router function

用来组合多个方法实现一个更高级的目的，这些方法之间有着一定的选择和排序关系， 只有被需要的代码才会被执行。

1
2
3
4
5
6
7
8
9
10
//Router Function

private func turnLights(on shouldTurnLightsOn: Bool) {
    if shouldTurnLightsOn {
        turnExteriorLightsOn()
        checkForBurnedBulbs()
    } else {
        turnExteriorLightOff()
    }
}

Router functions 通常直接调用 execution functions，但是偶尔也可以包含一些逻辑，如果这些代码没有超过一行的话。

4. Execution function

核心的方法实现，实现了方法名所描述的内容。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Execution Function

private func trunExteriorLightsOn() {
    leftFrontLight.isOn  = true
    rightFrontLight.isOn = true
    leftBackLight.isOn   = true
    rightBackLight.isOn  = true    
}

private func checkForBurnedBulbs() {
    for lightBulb in bulbs where !lightBulb.isUseable {
        Dashboard.display(errorType: .lights)
        break
    }
}

这个方法具体的逻辑我们可能很难完全去理解，但是我们早已经把它要做的事情写道了方法名里面。这个方法打开了灯光，并查看了是否有灯泡烧毁。理解这些将有助于我们定位bug，也更容易在不改变这些方法名的情况下，为其添加新的逻辑和特性。

最终， 当你的在项目当中实现了这个结构以后，你只需要在你的class实现中管理 informer, management, router 方法。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
class Car: Vehicle
{
// Informer Functions
   override func engineStarted()
   {
     super.engineStarted()
     handleCarStarted()
   }
// Management Functions
   private func handleCarStarted()
   {
     turnLights(on: true)
     turnAC(on: true)
   }
// Router Functions
   private func turnLights(on shouldTurnLightsOn: Bool)
   {
     if shouldTurnLightsOn
     {
       turnExteriorLightsOn()
       checkForBurnedBulbs()
     }
     else { turnExteriorLightsOff() }
     // When an if statment has only 1 thing to execute i like to write it
     // at the same line with the "if" "else" word, it makes reading your code more fluent.
   }
   private func handleTurnAC(on shouldTurnACOn: Bool)
   {
     if shouldTurnACOn
     {
       let tempeture = currentTemptureSelected()
       let toggleFocus = currentACToggleFocus()
       startAC(with: tempeture, aimedTo: toggleFocus)
     }
     else { turnACOff() }
   }
}

所有的 execution/logic 方法都可以放在class的扩展当中，在同一个文件内部。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
extension Car
{
// Execution Functions
  private func turnExteriorLightsOn()
  {
    leftFrontLight .isOn = true
    rightFrontLight.isOn = true
    leftBackLight  .isOn = true
    rightBackLight .isOn = true
  }
  
  private func checkForBurnedBulbs()
  {
     for lightBulb in bulbs where !lightBulb.isUseable
     {
       Dashboard.display(errorType: .lights)
       break
     } 
  }
}

结果就是你将得到一个简洁的、易读的、益于理解的类实现。

记住任何方法一定要遵守单一责任愿者

避免使用and在你的方法名当中：

  • playAndMinimize()
  • loadAndPlay()

这些错误的使用方法，打破了单一责任原则， 这样使你的代码看起来要适用于所有的场景。

避免在取方法名的时候玩猜一猜的游戏:

  • moveRedViewIfNeeded()

这个例子保证了，将来的每一个开发者都必须要亲自查看方法的内部实现，才能明确的知道哪种情况下会移动red view. 这样模棱两可的方法会增加阅读代码的难度。

但是 layoutIfNeeded 不是同样的情况， 我们都知道只有在 setNeedsLayout 是 true 的情况下，视图才会刷新布局。 类似的这种方法，通常情况下，最好保持只使用在你项目的私有方法里面。

小讨论

闪现在脑海中的第一件事情就是关于代码可读性的约定， 这些约定大家都知道，也经常被使用，但是使用这些约定不一定让你的代码更好了，它们会让代码俱备跨跨应用/跨平台的的能力，但是对可读性没有什么提升。

is 前缀应该被用在布尔属性，或是表示一个方法要返回布尔值 #代码约定

if总是被来表示布尔值， 为什么我们需要在使用布尔值时，在前面加上is呢？为什么苹果会修改 swift 的语法，从 view.hidden ~> view.isHidden? 我能想到的唯一答案就是 if view.isHidden 读起来感觉更加的地道。

让我们尝试着用以下规则来实现is前缀：

  • 如果一个类的布尔值属性或方法是公开的，那添加 is 就很合适
1
2
3
4
5
public var isHidden: Bool
{
  return alpha == 0.0
}
if containerView.isHidden
  • 如果一个类的布尔值属性或方法是私有的，那添加 is 就看起来很多余
1
2
3
4
5
6
7
8
9
private var positionedVerticaly: Bool
{
  return view.frame.width/2 == centerX
}
if positionedVerticaly
if positionedVerticaly && positionedHorizontally
VS
if isPositionedVerticaly
if isPositionedVerticaly && isPositionedHorizontally
  • 如果一个布尔值属性或方法私有的，但是可能要提供一个公开的取值方法，我们可以使用一个计算属性返回这个私有的值。
var isPositionedVerticaly: Bool
1
2
3
4
{
  return positionedVerticaly
}
if containerView.isPositionedVerticaly

我们也可以使用 private(set) 然后公开使用其属性。但是考虑到产生的副作用，我们决定使用这样的封装。

封装被用来隐藏来自于一个类当中的结构化数据或状态， 防止不确定的调用直接方法这些数据。封装

你可能会问，如果一个布尔值不是直接表示自己名字所代表的含义呢，在这种情况看下，你可以写的属性名类似于这样：

  • private var playerIsPlaying: Bool
  • private var gridConstraintIsEnabled()

is需要一些指代对象，view.isHidden 中的is指向 view。 在其它的一些例子当中也表达着同样的意思， playerIsPlaying 中 is 指向的是那个 player。

通常，相比去查看属性的声明，开发者更喜欢直接通过阅读代码中的变量而去猜测他们所代表的含义。

1
/if playerIsPlaying { }/ **opposing of** /if isPlayerIsPlaying {}/

以上那个看起来更舒服呢？由你来决定。