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)