Swift Tips: Documentation

Code documentation is always a tug-of-war between the desire to write beautiful “self-documenting” code and adding your own explanatory comments. Self-documenting code should always be the goal, but sometimes a simple comment will help save you time and mental fatigue.

To help you strike the right balance, we collected a few useful documentation tips to use around your codebase.

Quick Help

Xcode comes with a handy feature called Quick Help. This is the nice documentation pop-up you see when Option + Clicking around your codebase. The documentation also shows up in the Quick Help panel of the Utilities drawer. The Quick Help feature can really save you a lot of time by allowing you to stay in context when trying to remember what something actually does.

You also have the ability to create your own Quick Help documentation. Comments directly above a class, struct, enum, property, method, etc., of the form /// … or /** … */ will be rendered as Quick Help. Within this comment, you can use a Markdown-like syntax to write rich documentation that includes basic text formatting, sample code, links, and even images and videos. See Apple’s Markup Formatting Reference for all of the details.

A handy shortcut to remember is Command + Option + / when your cursor is on a function. This will auto-generate a ready-to-fill-in template for your function, including your list of parameters and return type.

Pro Tip: Playgrounds have their own unique documentation functionality, including the ability to render special comments (/*: … */ and //: …) into a beautiful, print-like format that is perfect for building training material for your team or even to use as a presentation medium.

Helpful Comments

Sometimes a simple comment is all you need to help jog your memory or point out something tricky in the code. Here are a few helpful conventions:

• // MARK: can be used to outline your code. These show up in the jump bar along with property and method declarations. They are Swift’s version of #pragma mark -.
• // TODO: is very useful when marking places for future work, especially when laying out subtasks needed to complete your current task at hand. These special comments show up in Xcode’s jump bar, so I like to make them stand out by wrapping the content in asterisks (e.g., // TODO: *** … ***). The comments should be short and to the point. If you need to provide more information, put it in another comment on the next line down. Your codebase should not be littered with unfinished TODOs. We’ll talk about one way to help prevent that shortly.
• // FIXME: is similar to TODO except that it usually denotes something that is broken, rather than incomplete. These should follow a similar convention as TODO, including not sticking around for long.
• // NOTE: is a useful convention to follow when leaving information about how something works or pointing out special considerations.
• // IMPORTANT: can be helpful in differentiating notes that are extremely important. You can also come up with your own schemes to mark important information.

Pro Tip: Sign and date your helpful comments (// NOTE: … ~ ABC 2017–02–07) so that people always know who wrote it. Blame can be lost in source control with a simple copy and paste during refactoring.

These special comments can be integrated directly into your build system. For example, wouldn’t it be nice if all of the // TODO: and // FIXME: comments showed up as Xcode warnings? This is possible and pretty easy to accomplish using a custom build phase. Tools like [swiftlint]() come preloaded with this functionality, but you can also roll your own with a simple script. Here’s an example script from Stack Overflow that flags TODOs and FIXMEs as warnings at compile time:

if [ “${CONFIGURATION}” = “Debug” ]; then
  TAGS=“TODO:|FIXME:”
  echo “searching ${SRCROOT} for ${TAGS}”
  find “${SRCROOT}” \( -name “*.swift” \) -print0 | xargs -0 egrep \
  — with-filename \
  — line-number \
  — only-matching “($TAGS).*\$” \
  | perl -p -e “s/($TAGS)/ warning: \$1/”
fi

Swift is still evolving, but getting into the habit of writing clear and consistent code with helpful documentation will serve you (and your teammates) well in the long run. If you have Swift documentation tips that we didn’t cover here, tell us about them in the comments below or share them with us on Twitter.

Be sure to check back next Monday as we dive into advice on organizing your projects.

For more insights on design and development, subscribe to BPXL Craft and follow Black Pixel on Twitter.

Black Pixel is a creative digital products agency. Learn more at blackpixel.com.