Swift — 善用註解,使程式碼更加明朗
讓我們看看如何使用註解,讓程式碼更容易閱讀吧!
✒︎ 前言:
今天這篇文章主要來介紹如何在 Xcode 中使用 Comment or Tag 的方式來註解你的程式碼,透過使用這種方式來告訴別人或提醒自己這段程式碼的用意或意圖。而我們也可以透過這種方式來區分我們的程式碼區塊,使我們的程式碼區塊內的職責更為清晰。
✒︎ 實作註解:
‣ 區分程式碼區塊:
首先我要帶給各位的第一個註解方式是我經常使用到的,方式為 // MARK:
以及 //MARK: -
,而這個註解方式通常是用來表示這個區塊或這段程式碼的內容,而這兩個不同的地方在於有 -
的註解會出現分隔線:
因此,我們試著放進去一些內容來查看它的實際狀況吧:
如此一來我們可以透過註解大概了解各個區塊中程式碼的內容,除此之外我們還可以透過這個方式來快速查找程式碼區塊,只要點選你想前往的內容程式碼就會跳轉到該區塊中:
而當我們有 extension 的時候也可以透過這種方式來區分程式碼區塊,像是當我們遵循了一個新的協議時,我們可以加上一個 MARK
:
這樣我們在查找的時候也能很快速找到該協議相關的實現內容:
而當如果你有開啟 Minimap 的功能的話,就能直接看到各個 MARK
後的區塊,我們也可以直接點選內容來前往該區塊:
如此一來,你對於你程式碼中的區塊內容將會更加了解。
‣ 幫函數添加描述:
在之前的文章有提起到使用 ///
的註解可以幫函數或屬性添加描述,像是:
但這邊我們還有更進階的做法,你可以看到 someFunction 中的 Parameters 都顯示 No description,所以表示其實我們也可以幫它新增函數的描述。首先,我們先按住 command 並點選該函數,接著選擇 Add Documentation 的操作:
接著你可以看到它幫我們的函數新增了幾段註解,我們就可以透過修改這些 description
來新增函數中的內容描述:
接著我們填寫好這些 description 之後,再次透過 option 與點擊函數查看其函數描述,你應該可以看到其中每個函數的內容描述:
如此一來就不怕其他人在調用的時候會錯意,透過這些描述可以讓調用者對於你這個函數有更深入的了解,並且也知道每個內容中的含義。
‣ Tag:
這邊當然我們也可以寫一些常見的註解,像是 // TODO:
用來說明待辦事項,// BUG:
來表示這邊程式碼還有一些問題,而或是 // FIXME:
來表示需要幫忙修正這段程式碼的問題。但是這邊的註解方式不會像上面的這些註解方式有特殊的效果,而就只是個單純的註解。
但我們可以透過邊寫 script 的方式,讓這些註解在使用時可以有更明顯的提示,這邊我們參考這篇文章的方式,在我們專案中的 Build Phase 上新增一個 Run Script,並且加入以下程式碼:
TAGS="TODO:|FIXME:"ERRORTAG="ERROR:"find "${SRCROOT}" \( -name "*.h" -or -name "*.m" -or -name "*.swift" \) -print0 | xargs -0 egrep --with-filename --line-number --only-matching "($TAGS).*\$|($ERRORTAG).*\$" | perl -p -e "s/($TAGS)/ warning: \$1/" | perl -p -e "s/($ERRORTAG)/ error: \$1/"
如此一來,當我們在使用 TAGS
所包含的註解時,會出黃色的提示。而當我們使用 ERRORTAG
所包含的註解時,則會出現紅色的提示,但是都能夠正常編譯。
‣ #waring & #error:
在 Xcode 中內建我們能夠使用 #warning
來表示警告以及使用 #error
來表示錯誤,而這對我來說也算是一種註解方式,這兩個方式都可以帶入一個 message
來說明其內容。因此,我們也可以像上面一樣註解 TODO
以及 ERROR
的訊息:
但比較特別的是,如果你的程式碼中有使用到 #error
的話,那麼編譯將會失敗,直到你的程式碼中不包含 #error
的錯誤時才能夠繼續正常編譯,算是一種強迫修正的方法。
✒︎ 後記:
以上這幾種就是我在 Xcode 常用到的註解方式,你可以為你自己或團隊打造一個註解方式,透過註解方式可以讓合作的其他人更了解你的程式碼內容,同時,也防止自己遺忘了這些程式碼內容,算是一舉兩得的方式。