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

Download this comprehensive Mobile Testing Reference Guide to help prioritize which mobile devices and OSs to test against, brought to you in partnership with Sauce Labs.

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.

Analysts agree that a mix of emulators/simulators and real devices are necessary to optimize your mobile app testing - learn more in this white paper, brought to you in partnership with Sauce Labs.

documentation ,swift

Published at DZone with permission of Simon Gladman, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

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

{{ parent.tldr }}

{{ parent.urlSource.name }}