Merge pull request github#4 from github/jspahrsummers-patch-1

jspahrsummers · jspahrsummers · commit cdae9ae43adc · 2014-08-01T13:07:53.000-07:00
Only explicitly refer to `self` when required
diff --git a/README.md b/README.md
@@ -47,8 +47,40 @@ However, definitions within those can leave access control implicit, where appro
 
 ```swift
 internal struct TheFez {
-    var owner: Person = Joshaber()
+	var owner: Person = Joshaber()
 }
 ```
 
 _Rationale:_ It's rarely appropriate for top-level definitions to be specifically `internal`, and being explicit ensures that careful thought goes into that decision. Within a definition, reusing the same access control specifier is just duplicative, and the default is usually reasonable.
+
+#### Only explicitly refer to `self` when required
+
+When accessing properties or methods on `self`, leave the reference to `self` implicit by default:
+
+```swift
+private class History {
+	var events: [Event]
+
+	func rewrite() {
+		events = []
+	}
+}
+```
+
+Only include the explicit keyword when required by the language—for example, in a closure, or when parameter names conflict:
+
+```swift
+extension History {
+	init(events: [Event]) {
+		self.events = events
+	}
+
+	var whenVictorious: () -> () {
+		return {
+			self.rewrite()
+		}
+	}
+}
+```
+
+_Rationale:_ This makes the capturing semantics of `self` stand out more in closures, and avoids verbosity elsewhere.	
