First Swift Style Guide

I’ve spent a good deal of time reading the Swift manual, to learn this critical new piece of Apple Technology. All the gray-haired old timers are learning it, spending at least as much time as fresh-outs for sure. We know only too well how fast and relentless Apple pushes its technology, and those who dally will be left in the dust.

So many have asked “What constitutes good Swift coding practices?”, the stock answer being “No one knows yet”. Well, one good step forward is to more or less agree on a coding style (even thought Apple’s sample code is all over the map). It seems that Ray Wenderlich posted a Swift Style Guide  around the start of August, and I just read it.

Mostly I agree with it, and remember that this style guide is for code posted on its site, so in some sense must be more readable than code we write for ourselves. Not sure about making my tab stops 2 spaces, but I can see the logic in it – the big problem for real coders is going to be switching back and forth between older ObjC code and Swift, so different tab stops is a huge PITA.

Now that Xcode 5 supports doxygen annotation, it’s time for you to start using it!

Ever since Xcode 5 added native support for doxygen, it really pays to annotate your code with doxygen style comments, which only require a few extra characters to comments you may already make.

In looking for tips and tricks, I turned up an excellent how-to written 4 years ago (but still correct) that offers many different techniques. For example, you can remind yourself (and others) how to use a particular variable:

 @property(assign) int ts; ///< Short Comment

or line wrap for up to 3 lines of comments:

@property(assign) int ts; ///< Set the complete ...
                          ///< the progress ...

If you’d rather use C-style comments you can:

@property(assign) int ts; /**< Set the complete ...
                               the progress ... */

The parser seems really smart about how finding continuation comments and also ignoring leading white space. In my examples, I indented the second lines, but you can leave them pegged to the left margin if you prefer.

The more common doxygen usage is to provide annotation blocks above methods, and the oodles of options you can use to do that can be found in this recent post on StackOverFlow (make sure to upvote the question and answer!):

You can add this handy code snippet to your Xcode Code Snippet library:

 @param <#parameter#>
 @returns <#retval#>
 @exception <#throws#>

as detailed here (and I just did!):

From then on you and others can get help during autocomplete, as well as by option-clicking on a method. I was slow to start using this, but now its getting to be second nature.

Also, if you start posting your open source code (using podspecs) to Cocoapods, they run doxygen on your files and create really nice documentation for them on CocoaDocs.