代码大家都会写,但是把注释写好却是一个技术活。
下面这段话,很好的说明了写好注释的感觉:
注释代码很像清洁你的厕所——你不想干,但如果你做了,这绝对会给你和你的客人带来更愉悦的体验。—— Ryan Campbell
Objective-C的代码注释
很久很久以前,在Xcode还可以安装插件的时代,iOSer都通过VVDocument来编写代码注释的。
代码注释的风格一般都是这样的,代码出自SDWebImageManager.h
/**
* Controls which image should be downloaded when the image is not found in the cache.
*
* @param imageManager The current `SDWebImageManager`
* @param imageURL The url of the image to be downloaded
*
* @return Return NO to prevent the downloading of the image on cache misses. If not implemented, YES is implied.
*/
- (BOOL)imageManager:(nonnull SDWebImageManager *)imageManager shouldDownloadImageForURL:(nonnull NSURL *)imageURL;
/**
* Controls the complicated logic to mark as failed URLs when download error occur.
* If the delegate implement this method, we will not use the built-in way to mark URL as failed based on error code;
@param imageManager The current `SDWebImageManager`
@param imageURL The url of the image
@param error The download error for the url
@return Whether to block this url or not. Return YES to mark this URL as failed.
*/
* (BOOL)imageManager:(nonnull SDWebImageManager *)imageManager shouldBlockFailedURL:(nonnull NSURL *)imageURL withError:(nonnull NSError *)error;
- OC的注释是通过/** */这样的形式进行编写的。
分隔符使用的是这种风格:
#pragma mark - 这个是一个分割符
- 需要注意的是这个-非常的重要,通过这个-,在查看代码的时候,可以生成分隔线,让代码结构看的更为清晰。
Swift的代码注释
随着Swift语言发布,在Swift中编写注释的风格就所有不同了:
extension NSObject {
/// 对象获取类的字符串名称
public var className: String {
return runtimeType.className
}
/// 类获取类的字符串名称
public static var className: String {
return String(describing: self)
}
/// NSObject对象获取类型
public var runtimeType: NSObject.Type {
return type(of: self)
}
/// 这是一个例子函数
/// - Parameter arg:
/// - Parameter argument: 传入Int类型的参数
/// - Returns: 返回Int类型的参数
public func afunction(argument: Int) -> Int {
return argument
}
}
- Swift的注释是通过/// 这样的形式进行编写的。
分隔符使用的是这种风格:
//MARK: - 绑定
- Swift中的//MARK:这个-也是起到生成分隔线的作用。
Objective-C和Swift的注释风格现在已经统一
如果你现在通过**alt+cmd+/**在OC和Swift中编写注释的时候,就会发现现在的注释都变成了Swift的这个中风格了:
/// 主要产品
/// - Parameter data: 出入字典 key: companyProducts
/// - Returns: CompanyCellModelable
func setProductModel(_ data: CompanyModel.CompanyProducts?) -> CompanyCellModelable? {
- 我个人建议是:以前代码注释就让它去吧,现在就都是用这个统一风格。
快速修改注释
一个函数写好了,注释也写好,但是有的时候计划没有变化快,函数添加了新的参数,这个注释难道要手动添加?
别急,其实Xcode也为我们提供了快捷方式,我们继续看例子,这个函数我在之前的基础上添加了一个num参数,但是注释还是之前的样子:
cmd+鼠标左键点击,我们可以看到左侧出现了一个菜单,点击Add Documentation
我们需要添加的参数它就来了,这样就可以直接添加注释了。
大家有兴趣可以把菜单的选项都点击试试,也许有意外的惊喜,比如Convert Function to Async,await/async。