iOS 開發：在 Xcode 中使用 Markdown 來撰寫註解
在寫程式的時候，適時地加上言簡意駭的註解，這個動作可說是相當重要。對團隊來說，這麼做能讓每個人在接手專案時，第一時間便能理解變數、函式們的作用；而對個人來說，可以確保自己在未來，能快速想起眼前的程式碼作用。
一般大家都會用 // or /* */ 的方式來撰寫註解，而這篇文章我想介紹給大家，如何利用 Markdown 格式的方式來寫註解，讓註解變得更清楚明瞭！
1) 設定 Xcode Preferences
首先我們要先做個顯示 Markdown 的快捷鍵設定，打開 Xcode 的 Preferences ( 快捷鍵 comment + , )
在 Key Building 中搜尋 Show Rendered，我自己的 Xcode 中，預設是沒有快捷鍵的，所以我在這自行設定快捷鍵為 Option + M
接者開啟一個專案，新增一個 Playground page 到專案中。
2) 以 Markdown 格式撰寫註解
如果要以 Markdown 的格式來撰寫註解，我們要在一般註解的方式後面加一個冒號，用法如下：
//: 單行註解
/*:
多行註解
*/
再加上 Markdown 的語法：
這時候我們只要按下我們剛剛所設定好的顯示 Markdown 快捷鍵，神奇的事情就會發生了。
用這種方式來撰寫 Project 的文件，就不需要再額外使用 Google doc 或是 Word 來寫專案文件，當新的成員加入專案開發時，也能快速地找到相關文件來閱讀，減少新成員了解專案的所需時間。
3) 自行撰寫 Quick Help
如果想要直接為函式 (function) 撰寫一個 Quick Help 的註解，可利用三個斜線開頭，搭配 Markdown 語法：
撰寫完後，只要點擊函式名稱，則可以在右邊的 Quick Help 上，看到你自己所撰寫的註解。
若是多行註解，則使用斜線加兩個星號 (/**) 為開頭，結束部分則一樣是星號加斜線 (*/) ，在這邊要特別注意的是，如果你想要直接以條列式的方式顯示在 Quick Help ，在個單項的星號前，需要多加一個空白，不然 Xcode 會無法辨識。
4) Xcode 預設 Documentation 模板
當我們寫好一個函式後，我們也可以直接叫出 Xcode 預設好的 Documentation 模板，來撰寫註解。
先連續點擊函式名稱，函式被選取後，點滑鼠右鍵，選擇 Structure 中的 Add Documentation：
此時你會看到，在函式上頭會出現利用多個單行註解，所撰寫而成的模板：
此時你只需要填寫函式的敘述、所需參數的描述、回傳值的描述，這三大註解，便能讓下一位看 code 的人，清楚明白這個函式的用法。
小結
過去我曾用過其他幾款 IDE 來撰寫程式，但第一次看到這樣寫註解的方式，讓我感到相當驚訝！相信各位看完這篇文章後，也能在自己的專案中，寫下清楚明瞭的註解，為往後回頭看專案的自己，或專案的新成員，省下理解函式的時間。
如果想知道更多的介紹，可以到 Apple 的開發人員網站，裡頭有著更詳盡的說明。如果你有不同的方法，也歡迎留言給我交流參考。
【AppWorks School 新班 — Android Class #1 與 iOS Class #6 限時招生中】遠距 4 週、駐點集訓 16 週，全程免費，幫助你成為新時代的軟體工程師。
Android Class #1 >> https://goo.gl/Efi23t
iOS Class #6 >> https://goo.gl/Xz27kK
歡迎申請加入，來讓我們幫助你加速學習！(申請只到 01/07/2018)
