Annotating Swift Code

todo, fixme and compiler directives

Image for post
Image for post
Photo by KOBU Agency on Unsplash

Xcode allows you to annotate your code to make it easier to navigate your code, and potentially fix problems. This guide will help you to do just that!

Difficulty: Beginner | Easy | Normal | Challenging

Prerequisites:

Terminology

Compiler: A program that converts instructions into a machine-code or lower-level form so that they can be read and executed by a computer

Compiler Directives: A way to specify how the compiler should process input

Simple Annotation

When you create annotations they appear in the navigation.

The example

So imagine you have a situation where you’ve a piece of code that needs fixing. You decide to use the FIXME annotation. You also want to use the camera, but decide to learn how to use it using a tutorial before you implement the camera. To do so, you use the TODO annotation (I’ve placed this annotation within the function takePicture).

func takePicture() -> Bool {
// TODO: Do camera stuff
return true
}

and similarly I’ve placed a FIXME in the broken increment function

func increment(_ num: Int) -> Int {
// FIXME: Make this increment the input
return num
}

As a result the FIXME and TODO arrive in the jump bar.

Image for post
Image for post

We can show how this can appear, and once you select one of the annotations in the list you can just straight to that point in the code! Neat!

Image for post
Image for post

#warning
We can create a warning using #warning to give a programmer a warning that the increment function above doesn’t display the correct answer:

func increment(_ num: Int) -> Int {
// FIXME: Make this increment the input
#warning("Incorrect result returned")

return num
}

which in Xcode would look like the following:

Image for post
Image for post

Giving a clear indication that the incorrect results are returned. Even in command-line builds.

Nice.

#error
We can implement a similar

func readArr(_ arr: [Int]) {
for i in 0…arr.count {
if i == arr.count {
#error(“err”)
}
}
}

Giving a clear indication of an error, also in command-line builds.

Image for post
Image for post

This will of course stop the code from building in Xcode, like any error would do so.

Detect the simulator

You might have code that just won’t work on the simulator since it does not have the features that your code requires. As a simple example, there simply isn’t a camera on the device.

@discardableResult
func takePicture() -> Bool {
#if targetEnvironment(simulator)
// TODO: Do camera stuff
return true
#else
return true
#endif
}

Now the code doesn’t have any performance impact on devices (so this is actually ideal for production code as there is no performance impact on user devices — it is like nothing happened).

Conclusion

Using these compiler directives makes your code easier to read, and allows warning and errors to be placed into your code which allows you to make your code much more readable and (arguably) nicer.

This should make your code more professional, and make you of further use in your organisation.

Who wouldn’t want that? I’ve prepped a whole project so you can see this code in use. Where? You can download it from right here.

Extend your knowledge

Questions

You can get in touch with me HERE; I’m usually available on Twitter so can get back to you…fast

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store