Eon's swift blog

Swift doc formating

Jul 31, 2021
5 minute read

My notes on method commenting in swift.

  • Commenting is vital when creating complex systems. Without documentation in the code, much of the resolution about how the method came to be and its artifacts and gotchas can be lost.
  • Personally, I include massive amounts of comments in the code because when I revisit the code a year later, my initial thinking has disappeared and I need something to accelerate my reasoning to get back into the code.
  • I also leave references to where parts of the solution were found, such as Stack Overflow links or other GitHub projects, or GitHub issues where the solution was discussed. This gives credit where credit is due.
  • I use a commenting style that is closer to JavaDoc, as it is widely known and feels universal. It even renders to Apple’s dialog boxes like the one below: ```swift /**
    • A method that returns awesome colors
      • Parameters:
      • color: only awesome colors allowed
      • alpha: only awesome alpha values allowed
      • Returns: A color with new alpha value */ static func test(color: UIColor, alpha: CGFloat) -> UIColor { _ = color _ = alpha return color.withAlpha(alpha) }

Hold down the `alt` key and press the method name from a caller. And this dialog will pop up

<img width="430" alt="img" src="https://rawgit.com/stylekit/img/master/Screen Shot 2018-07-31 at 11.07.30.png">

#### Java-doc (Naked):

```swift
/*
  When you copy/paste, indentation is lost, also it's hard to see if the indentation is correct or not
       Here
*/

Obj-c era commenting:

///
/// This commenting style is pretty common in the swift community
/// One drawback is that you have to click 3 times every time you want to add another line
/// This commenting style is used in obj-c and swift but not in many other languages
///

Java-doc style (Regular)

/**
 * This commenting style is used in many languages and is over all the most common
 * Example:
 * var temp = {
 *      //something indented. A comment style keeps indentation on copy paste.
 * }
 */

Comment style:

class Human {
    /**
     * This method feeds a certain food to a person.
     * - parameter food: The food you want to be eaten.
     * - parameter person: The person who should eat the food.
     * - returns: True if the food was eaten by the person; false otherwise.
     * - throws: see DecodingError
     */
    func feed(_ food: Food, to person: Human) -> Bool {
        // ...
    }
}

Mentioning classes, variables etc:

Use code ticks
/**
 * This does something with a `UIViewController`, perchance.
 * - warning: Make sure that `someValue` is `true` before running this function.
 */
func myFunction() {
    /* ... */
}

Expressive comment style

/**
 * Writes the textual representation of each    ← Summary
 * element of `items` to the standard output.
 *                                              ← Blank line
 * The textual representation for each item `x` ← Additional discussion
 * is generated by the expression `String(x)`.
 *
 * - Parameter separator: text to be printed    ⎫
 *   between items.                             ⎟
 * - Parameter terminator: text to be printed   ⎬ Parameters section
 *   at the end.                                ⎟
 *                                              ⎭
 * - Note: To print without a trailing          ⎫
 *   newline, pass `terminator: ""`             ⎟
 *                                              ⎬ Symbol commands
 * - SeeAlso: `CustomDebugStringConvertible`,   ⎟
 *   `CustomStringConvertible`, `debugPrint`.   ⎭
 */
 public func print(_ items: Any..., separator: String = " ", terminator: String = "\n"){}

Expressive comment style (w/ Markdown)

If the code is complicated or unusual etc:

/**
 * ## Feature Support
 *
 * This class does some awesome things. It supports:
 *
 * - Feature 1
 * - Feature 2
 * - Feature 3
 *
 * ## Examples
 *
 * Here is an example use case indented by four spaces because that indicates a
 * code block:
 *
 * let myAwesomeThing = MyAwesomeClass()
 * myAwesomeThing.makeMoney()
 *
 * ## Warnings
 *
 * There are some things you should be careful of:
 *
 * 1. Thing one
 * 2. Thing two
 * 3. Thing three
 */

Swift syntax keywords:

The keywords available in the swift commenting syntax

  • Attention
  • Author
  • Authors
  • Bug
  • Complexity
  • Copyright
  • Date
  • Experiment
  • Important
  • Invariant
  • Note
  • Parameter
  • Parameters
  • Postcondition
  • Precondition
  • Remark
  • Requires
  • Returns
  • SeeAlso
  • Since
  • Throws
  • ToDo
  • Version
  • Warning

Codebases that are heavily commented:

https://github.com/IBM-Swift/Kitura https://github.com/CosmicMind/Motion https://github.com/CosmicMind/Material

In closing (Comment or not to comment)

Not to comment:

  • Some developers claim that if the code is well written then there is no need to comment the code
  • Some developers claim that documentation is never updated so it becomes outdated etc

To comment:

  • Applications used to be simple primitive scripts that were easy to reason about. However, today’s apps are increasing in complexity and some are even becoming platforms, making them no longer easy to reason about. Therefore, we need context in the slice we are currently working in, as it’s close to impossible to understand the whole structure at any one point.
  • If you go in as a ‘swat team’ to fix a one-off bug, having contextual comments can save you a lot of time when trying to reason about implications.
  • Having contextual comments also avoids deprecating your development skills. If you spend your days wandering clueless through wades of code, you decrease your skills. Instead, spend your time creating things the proper way and nurturing them, rather than fixing someone else’s rush job.
  • The main point about contextual code comments is that developers have a finite amount of brain bandwidth available each day, which is most efficiently spent on solving problems rather than trying to understand intent. We write so much code in lots of different places that we quickly lose our bearings. As such, we need clues in the code to derive context blazing fast and just get going, surfing on top of the wave instead of under it.
  • When you have a codebase that is thoroughly commented, you can use external services to auto-generate searchable help documents, similar to Apple’s own help documents.
  • It’s important to write a documentation comment for every declaration. Insights gained by writing documentation can have a profound impact on your design, so don’t put it off.
  • Comments are also non-destructive, meaning they don’t change how apps behave. This means you can safely improve them without breaking anything. It’s also a nice way to get back into code. Go over the comments and improve them to bring your neural network up to speed and solve things more easily.