Add code organization convention (#26)

* Add guide on comments

* Add Casting convention

* Add code organization convention

* Renamed File Content Ordering to File Organization

Co-authored-by: Chen Yang <yangche@microsoft.com>

FileOrganization.md

@@ -1,6 +1,6 @@
-# File Content Ordering
+# File Organization
 
-## Convention
+## Convention - Ordering
 
 Most "important" stuff at the top; and least "important" stuff at the bottom. The importance is usually determined by the [access level](https://docs.swift.org/swift-book/LanguageGuide/AccessControl.html); the less restrictive the access level, the more "important" it is.
 
@@ -62,6 +62,60 @@ internal func updateUnalliedHouses(_ houses: [House]) {
 private maximumHouseSize: Int = 50
 ```
 
+## Convention - Grouping
+Use `// MARK: Some text comment` to group related methods into sections. For example, in a view controller class, there might be `Setup`, `Layout`, and `Event Handlers` sections. 
+When marking a section of methods belonging to a superclass or a protocol, use the actual name of the superclass or protocol type instead of a loose translation. If there are multiple protocols, methods should be grouped by individual protocols. Note: this convention only applies to protocol adoption without extensions because the keyword `extension` will automatically put the protocol section in its own group.
+
+## Rationale
+Grouping related methods into sections help with code organization and navigation.
+
+## Examples
+
+``` swift
+
+// bad: does not use the name of the protocol as the name of the section
+// MARK: - Table view delegate
+...
+
+// good: use the name of the protocol directly as the name of the section
+// MARK: - UITableViewDelegate
+...
+
+// bad: using the same section for UITableViewDelegate and UITableViewDataSource protocols
+
+// MARK: - UITableViewDelegate and UITableViewDataSource
+
+public func tableView(_ tableView: UITableView, viewForHeaderInSection section: Int) -> UIView? {
+	...
+}
+
+public func numberOfSections(in tableView: UITableView) -> Int {
+	...
+}
+
+public func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
+	...
+}
+
+// good: using different sections for UITableViewDelegate and UITableViewDataSource protocols
+
+// MARK: - UITableViewDelegate
+
+public func tableView(_ tableView: UITableView, viewForHeaderInSection section: Int) -> UIView? {
+	...
+}
+
+// MARK: - UITableViewDataSource
+
+public func numberOfSections(in tableView: UITableView) -> Int {
+	...
+}
+
+public func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
+	...
+}
+```
+
 ## Convention - Constants
 
 Use structs or nested structs to group constants when possible; the grouping should be based on logical use instead of structure or type of the constants.

README.md

@@ -11,7 +11,7 @@ The Swift coding conventions guide documents many best practices for writing Swi
 * [Comments](Comments.md)
 * [Delegates](Delegates.md)
 * [Early Return](EarlyReturn.md)
-* [File Content Ordering](FileContentOrdering.md)
+* [File Organization](FileOrganization.md)
 * [Immutability](Immutability.md)
 * [Naming](Naming.md)
 * [Property Observers](PropertyObservers.md)