Use Markup to elevate your Swift code in Xcode

Have you ever inherited a codebase that is awful to work with? Maybe it’s so poorly written or organized that it’s hard to know what is going on? I bet most of you reading this have experienced this. Or maybe there is a humble few that readily admit that they caused this mess. Either way, writing good code is hard. There are many ways to improve a codebase, but I’d like to focus on one of those ways: using markdown in your code. In this article, I am going to talk about what markdown is in Xcode and how it can help clean up, organize, and even elevate your code.

What is Markdown?

In Xcode, markdown is used to format text through symbols for both playgrounds and QuickHelp. QuickHelp is a feature that allows the developer to option+click on a piece of code and it will pull up the documentation for that piece of code.

In-line Comments vs Quick Help Comments

There are two types of comments that can be used in Xcode. The first is In-line comments, and it’s done by typing two forward-slash characters.

// this is an in-line comment

In-line comments are useful for explaining things in code that might not be readily obvious to the reader. Maybe there’s a function that purposefully omits an algorithm because of a unique edge case. An in-line comment can tell the future developer that there is a purpose in leaving out this algorithm.

The other type of comment is a Quick Help comment. This is a comment that will be displayed in a formatted way in the Quick Help view. This is done by adding three forward-slash characters. This type of comment opens up a lot of the features that markdown has to offer.

Here’s what it will look like when you option-click on the variable you just wrote the comment for at the call site.

Now you can read the description from the call site instead of going to the implementation.

There are a ton of different attributes that can be used here to show in the Quick Help view. This can make your comments precise and organized. Here is a comprehensive list of all the available markdown attributes that you can use in Xcode.

Hotkey to document faster

With the number of different attributes you can use, it’s easy to get detailed in your documentation. But it’s also quite a bit of boilerplate code to write each time. Xcode has a hotkey that will automatically recognize the code and populate the markdown describing it. All you have to do is put your cursor on the name of the type (variable, struct, class, function, etc.) and press option+command+forward-slash. Try it out!

Notice how the description, parameters, and returns keywords are automatically inserted into your documentation. This gives you a head start on documenting your code.

Organize Your Code

Have you ever had a file that is really long and you were trying to find a specific function or variable? Using command+f is a good tool to find something if you know what to search for. However, Xcode has another cool feature to help with this. Towards the top of the Xcode editor, there is what looks like a breadcrumb trail of the file that you’re on. But the bread crumb goes even down to where your cursor is in the file. If you select that last option, you’ll see a list of variables and functions for that file. Select something on that list and you’ll be taken right to it. This feature makes looking through a large file a piece of cake. But there are ways to make this even more helpful with the uses of MARK, TODO, and FIXME keywords. Below is some code for reference.

This code uses MARK, TODO, and FIXME to help organize the code.

MARK

You can use the MARK keyword to separate and add organization to your code. One way I use this is I add a MARK keyword to organize my public and private methods.

Now select the dropdown of all of our methods. We now see the separation. Cool!

FIXME

You can use the FIXME keyword to signify that something needs to be fixed. Using this identifier has a couple of benefits. The obvious one is using it consistently makes it easy to look up with a project-wide search. But adding this also shows up in the dropdown menu.

TODO

You can use the TODO keyword to signify tasks that need to be done (refactoring, adding functionality, etc). It works the same as the other keywords. It also shows up in the drop-down menu to get your attention.

Conclusion

With markdown in Xcode, we can provide more detailed documentation that with the Quick View. We can also organize or code much better and find the code we need quickly. Take advantage of markdown and use it often in your codebase. Implementing these simple tricks will make your code more readable and easier for yourself and other developers to understand.

If you like this article, follow me on Medium because I write regularly.