Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

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

Launching an app doesn’t need to be daunting. Whether you’re just getting started or need a refresher on mobile app testing best practices, this guide is your resource! Brought to you in partnership with Perfecto

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.


Keep up with the latest DevTest Jargon with the latest Mobile DevTest Dictionary. Brought to you in partnership with Perfecto.

Topics:
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.

THE DZONE NEWSLETTER

Dev Resources & Solutions Straight to Your Inbox

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

X

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

{{ parent.tldr }}

{{ parent.urlSource.name }}