Original article, welcome to reprint. Please indicate: Guan Dongsheng's blog
As mentioned earlier , there are two syntaxes for Swift comments: single-line comments ( // ) and multi-line comments ( /*...*/ ). Here's an introduction to their usage specifications.
1. File Notes
The file comment is to add a comment at the beginning of each file. The file comment usually includes the following information: copyright information, file name, module, author information, historical version information, file content and function, etc.
Here's an example of a file comment:
/*
Copyright (C) 2015 Eorient Inc. All Rights Reserved.
See LICENSE.txt for this sample’s licensing information
Description:
This file contains the foundational subclass of NSOperation.
History:
15/7/22: Created by Tony Guan.
15/8/20: Add socket library
15/8/22: Add math library
*/
This comment only provides copyright information, file content and historical version information, etc. The file comment should include the content according to its actual situation.
2. Documentation Notes
Documentation comments are such comments that generate API help documentation. Documentation comments are mainly for functions such as types, properties, methods or functions.
Documentation comments are single-line comments ( // ) and multi-line comments ( /*...*/ ) after a little "hands", they become documentation comments, single-line documentation comments ( /// ) and multi-line documentation comments ( /**...*/ ).
Code example below:
import Foundation
/**
The protocol that types may implement if they wish to be
notified of significantoperation lifecycle events.
*/
protocol OperationObserver {
/// Invoked immediately prior to the `Operation`'s `execute()` method.
func operationDidStart(operation: Operation)
}
Documentation comments are used in the code.
Some tools can be used to generate API files from these documentation comments
3. Code comments
To process documentation comments in the program code, it is also necessary to add code comments in some key places. Documentation comments are generally helpful documents for people who cannot see the source code, while code comments are for reference by people who read the source code. Code comments generally use single-line comments ( // ) and multi-line comments ( /*...*/ ).
Sometimes comments are also made at the end of the code, which requires the comment content to be extremely short, and there should be enough space to separate the code and comments. The sample code of the tail annotation is as follows:
init(timeout: NSTimeInterval) {
self.timeout = timeout //initialization
}
4、使用地标注释
随着编码过程深入，工程代码量会增加，任何在这大量的代码中能快速找到需要方法或者是刚才修改过代码呢？
在Swift代码中使用地标注释，然后就可以使用Xcode工具在代码中快速查找了。地标注释有三个：
<!--[if !supportLists]-->l <!--[endif]-->MARK，用于方法或函数的注释。
<!--[if !supportLists]-->l <!--[endif]-->TODO，表示这里代码有没有完成，还要处理。
<!--[if !supportLists]-->l <!--[endif]-->FIXME，表示这里修改了代码。
这些注释会出现在Xcode的 Jump Bar中。来看一个示例：
class ViewController: UIViewController,
ÊUITableViewDataSource, UITableViewDelegate {
var listTeams: [[String:String]]!
override func viewDidLoad() {
super.viewDidLoad()
...
}
override func didReceiveMemoryWarning() {
super.didReceiveMemoryWarning()
//TODO: 释放资源 //使用TODO注释
}
// MARK: UITableViewDataSource 协议方法 //使用MARK注释
func tableView(tableView: UITableView,
ÊnumberOfRowsInSection section: Int) -> Int {
return self.listTeams.count
}
func tableView(tableView: UITableView,
ÊcellForRowAtIndexPath indexPath: NSIndexPath) -> UITableViewCell {
let cellIdentifier = "CellIdentifier"
let cell: UITableViewCell! = tableView
Ê.dequeueReusableCellWithIdentifier(cellIdentifier,
ÊforIndexPath: indexPath) as? UITableViewCell
// FIXME: 修改bug //使用了FIXME注释
let row = indexPath.row
let rowDict = self.listTeams[row] as [String:String]
...
return cell
}
// MARK: UITableViewDelegate 协议方法 //使用MARK注释
func tableView(tableView: UITableView,
ÊdidSelectRowAtIndexPath indexPath: NSIndexPath) {
...
}
}
上述代码中使用三种地标注释，在使用时候后面要跟有一个冒号(:)。
注释之后如果使用呢？打开Xcode的 Jump Bar，如下图，这些地标注释会在下拉列表中粗体显示，点击列表项就会跳转到注释行。
