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

jspahrsummers · jspahrsummers · commit a5d2a348655b · 2014-07-29T21:07:17.000-07:00
When to include access control specifiers
diff --git a/README.md b/README.md
@@ -32,3 +32,23 @@ subscript(index: Int) -> T {
 ```
 
 _Rationale:_ The intent and meaning of the first version is clear, and results in less code.
+
+#### Always specify access control explicitly for top-level definitions
+
+Top-level functions, types, and variables should always have explicit access control specifiers:
+
+```swift
+public var whoopsGlobalState: Int
+internal struct TheFez {}
+private func doTheThings(things: [Thing]) {}
+```
+
+However, definitions within those can leave access control implicit, where appropriate:
+
+```swift
+internal struct TheFez {
+    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.
