Organize Your Swift Project With Annotations, TODO's and FIXME's

It is important that you structure the code you write as best as you can. This may feel tedious at first because you don't exactly know what goes where. Over time you develop a structure that fits and you don't even think about it. It becomes second nature. By adding structure, it is much easier to navigate a project and stay on top of the code you write.

Adding Comments

Comments can greatly improve the readability of the code you write, but they are also useful to organize and browse a project. The comment I use the most to structure a Swift file is // MARK: -. Let's create blank project and see how this short comment can help us.

Let me show you an example. I always prefix the view life cycle methods with a MARK comment that reads View Life Cycle. It looks like this. The leading dash or hyphen adds a separator line before the title. You can also add a trailing dash or hypen to add a separator line after the title. That's a personal preference.

import UIKit

class ViewController: UIViewController {

    // MARK: - View Life Cycle

    override func viewDidLoad() {
        super.viewDidLoad()

        // Setup View
        setupView()
    }

    // MARK: - View Methods

    private func setupView() {
        // Configure View
        view.backgroundColor = .black
    }

}

It visually structures the code in the Swift file, but it also helps navigating the file in two interesting ways. By pressing Control + 6, you can browse the contents of the file using the jump bar at the top of the editor. The dash or hyphen in the MARK comment adds a horizontal line or separator line above the title. By using this technique, you split the contents of the source file up into sections that are easier to browse and manage.

This technique also helps if you are using the minimap in Xcode 11. The minimap shows a horizontal line or separator line above the title, making it easy to quickly jump to the section you're interested in.

Adding a TODO

Some developers prefer to leave the implementation of a type or method empty and add a note as a reminder. You could use a simple comment, but it's very easy to forget about tat comment. A much better solution is adding a TODO comment. Xcode has built-in support for this. You add a comment and start it with the keyword TODO. Take a look at the example below.

// MARK: - View Methods

private func setupView() {
    // Configure View
    view.backgroundColor = .black

    // TODO: Setup View Hierarchy
}

The TODO item shows up in the jump bar at the top of the editor. It is prefixed with a tiny checklist icon to set it apart from other annotations. This makes it easy to quickly jump to any tasks that you need to take care of.

Adding a FIXME

If you know you're introducing a bug or another type of issue, you can add a placeholder to remind you to fix the problem at a later point in time. This is very similar to adding a TODO. The difference is that you replace TODO with FIXME.

// MARK: - View Life Cycle

override func viewDidLoad() {
    super.viewDidLoad()

    // Setup View
    setupView()

    // FIXME: Fix Bug
}

The FIXME item shows up in the jump bar at the top of the editor. It is prefixed with a tiny bandaid icon to make it stand out from other, less important, annotations.

Taking it One Step Further

You could take it one step further by adding a build phase that generates a warning for every TODO and FIXME that hasn't been addressed. This is very useful since you probably don't want to ship an application that has one or more TODO's or FIXME's.

You can also use SwiftLint for this. SwiftLint is easy to add to a project using CocoaPods. After installing SwiftLint, create a build phase for SwiftLint and add the todo rule to the SwiftLint configuration file at the root of the project. When you build the project, SwiftLint automatically generates warnings for any TODO's and FIXME's.