目錄
普通注釋
結構性或者功能提示: MARK、TODO、FIXME
編譯器提示
文檔注釋
Playground注釋
今天,我知道我寫是什麼,上帝和我知道
明天,我知道這個代碼什麼意思,
後天,我知道這是我寫的代碼,
一周後,這TM誰寫的代碼,此時隻有上帝才知道啥意思
論代碼注釋的重要性。
普通注釋
普通注釋主要為了提示編碼和閱讀者,邏輯注釋等作用,一般不會在文檔中提示。
1. 單行注釋 //
var str = ""
// 修改str變量的值
str = "a new value"
2.多行注釋
/*
這裡是多行注釋
多行注釋裡也可以成對出現
/*
子注釋
*/
*/
code
結構性或者功能提示: MARK、TODO、FIXME
MARK: 代碼檔案結構标記,可以顯示檔案的大緻結構和子產品,說明建議使用首字母大寫
// MARK: - Properties
// MARK: - Initialization
// MARK: - IBAction Method
// MARK: - XXXDelegate
TODO: 待完成标記, 代表此處有需要完成的功能或者後續開發。
// TODO: - 待完成的功能
// TODO: - Need to finish
FIXME: 檢查标記, 通常用于需要檢查的地方,比如臨時修改變量為固定值友善測試,或者為了走通流程,注釋部分代碼等,都需要添加标記,友善後期提醒自己,萬一忘了。最好上線前全局搜尋檢查下。
代碼檔案結構(Ctr + 6 )
![](https://img.laitimes.com/img/__Qf2AjLwojIjJCLyojI0JCLiAzNfRHLGZkRGZkRfJ3bs92YsYTMfVmepNHLx0kaOdXSU9EMFpHW4Z0MMBjVtJWd0ckW65UbM5WOHJWa5kHT20ESjBjUIF2X0hXZ0xCMx81dvRWYoNHLrdEZwZ1Rh5WNXp1bwNjW1ZUba9VZwlHdssmch1mclRXY39CXldWYtlWPzNXZj9mcw1ycz9WL49zZuBnLyAzM5EDMycTM5IDNwkTMwIzLc52YucWbp5GZzNmLn9Gbi1yZtl2Lc9CX6MHc0RHaiojIsJye.png)
代碼檔案結構
編譯器提示
有些提示,我們希望在編譯期間就看到定制提示或錯誤,我們就可以使用如下标記:
#error:編譯器編譯到這裡就會停止,并展示攜帶的 message
#warning: 編譯器編譯到這裡就會提示 message 資訊
示例:
#warning("Needs to be refactored")
// some dodgy code here
#if !canImport(UIKit)
#error("This framework requires UIKit!")
#endif
#error使用情況示例:SDK API key, 代碼中必填資訊提示,标記目前完成任務在哪裡(以便下次接着開發)等情況。
原了解釋參考diagnostics-warning-error,apple開源提案描述
文檔注釋
單行注釋快捷鍵:⌘⌥/ 【 CMD + Alt + / 】
文檔注釋用于輸出代碼文檔和閱讀友善,規範的文檔可以在Quick Help中看到或者Alt + 左鍵快速檢視相關說明。更或者可以輸出說明文檔給别人使用
文檔注釋也分為單行和多行,不過根據蘋果Swift 開源代碼可以看出 基本都使用單行注釋
文檔注釋的對象: 自定義類型、變量、方法等,但是重點還是方法說明
Tip: 由于文檔注釋通常是多行和多辨別字段, 是以此時就可以用Xcode Code Snippet 代碼段收藏與引用
單行注釋 ///
類型文檔說明
/// 使用者資訊
struct UserInfo {
/// 昵稱
var nickname: String
/// 性别 ture: 男, false: 女
var isMale: Bool
}
可惜的是Swift 沒有發現對屬性的行尾注釋。
方法文檔說明
/// 文檔注釋參考 【單行】
/// - parameter pram: 單參數
/// - returns : 傳回結果是否成功 ture: 成功 false: 失敗
///
/// 其他discussion 詳細說明 // 【注意】必須隔一行
func singleLineComment(pram:String) -> Bool {
print("注釋參考")
return true
}
多行注釋
/**
文檔注釋參考 【多行注釋】 // 【注意:必須新起一行】
- parameter p1: The number of Llamas spotted on the trip
- parameter p2: The number of Llamas spotted on the trip
- returns: 傳回結果字元串數組
其他discussion說明 // 【注意】同樣必須隔一行
*/
func text(p1:String , p2:Bool) -> [String] {
return [String]()
}
支援 markdown 文法
除了使用關鍵字比如ruturns 來讓文檔更好看之外,我們還可以使用markdown豐富說明。單行和多行文檔注釋都支援markdown,但是這個時候個人建議就使用多行注釋
/**
# 支援markdown
# 一級标題
## 二級标題也可以的
注釋參考2
隔一行表示換行d
三個”***"代表一條分割線
***
## 使用示例
```
let result = testComment2(pram: "參數1", param2: true))
```
****
- important:這個很重要
- returns: 有傳回值
- parameter pram: The cubes available for allocation
- parameter param2: The people that require cubes
*/
func testComment2(pram:String, param2:Bool) -> Bool {
print("markdown支援")
return true
}
Quick Help 顯示
playground 示例代碼: gitee
swift Documentation
Playground注釋
蘋果官方文檔: Xcode Help -- Use playgrounds
Playgound 也支援markdown , 而且還可以做成跳轉文檔的模式。
比如,官網Sample Code, JSON與模型互轉 下載下傳即可
代碼限制規範
對于平時的代碼規範,Swift 語言可以使用 SwiftLint 工具來限制。對代碼習慣進行強限制,不符合的将提示警告或錯誤。
具體內建步驟參考 SwiftLint 官方文檔
下面是 Cocoapod 檢查腳本優化版本(隻檢查變動檔案,避免全局檢查,省略編譯時間)
# Run SwiftLint
START_DATE=$(date +"%s")
SWIFT_LINT="${PODS_ROOT}/SwiftLint/swiftlint"
# Run SwiftLint for given filename
run_swiftlint() {
local filename="${1}"
if [[ "${filename##*.}" == "swift" ]]; then
# ${SWIFT_LINT} autocorrect --path "${filename}"
${SWIFT_LINT} lint --path "${filename}"
fi
}
if [[ -e "${SWIFT_LINT}" ]]; then
echo "SwiftLint version: $(${SWIFT_LINT} version)"
# Run for both staged and unstaged files
git diff --name-only | while read filename; do run_swiftlint "${filename}"; done
git diff --cached --name-only | while read filename; do run_swiftlint "${filename}"; done
else
echo "${SWIFT_LINT} is not installed."
exit 0
fi
END_DATE=$(date +"%s")
DIFF=$(($END_DATE - $START_DATE))
echo "SwiftLint took $(($DIFF / 60)) minutes and $(($DIFF % 60)) seconds to complete."