Over a million developers have joined DZone.

Book Review: Swift Documentation Markup by Erica Sadun

DZone 's Guide to

Book Review: Swift Documentation Markup by Erica Sadun

We've all joined enough projects without comments, so don't let your latest Swift app fall to the dark side

· Mobile Zone ·
Free Resource

For me, there’s always been a temptation to avoid documenting code for personal projects. My code is, in my opinion, so beautifully self documenting that it doesn’t need an additional narrative. However, and I’m sure I’m not alone here, that lack of documentation can make my “future me” hate my “non-documenting me”.

Erica Sadun’s new book, Swift Documentation Markup, an Illustrated Tour, not only explains the importance of documentation, it also comprehensively details the breadth of Xcode’s markup support. 

Until I read the book, I had no real idea of just how powerful this support was. In a series of clearly written sections, Erica explains how to implement features such as text formatting, category keywords and even embedded images with real world demonstrations, examples of how Apple use them and recommendations on whether they should actually be used.

The ability to add rich content to documentation means that creating code comments now feels more of a creative process and there’s a certain satisfaction to option-clicking your carefully crafted function to see a beautifully formatted comment appear. This in itself is a incentive to start documenting properly.

So, thanks to Erica, expect to see a massive improvement in my own code documentation from now on. 

Best of all, this book is super inexpensive and is probably worth the price for the beautifully illustrated cover alone. Expect to see Erica’s other book cover illustrations on t-shirts at WWDC 2016!

Swift Documentation Markup, an Illustrated Tour is available here.

documentation ,swift

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}