Xcode中代码注释编写小技巧
前言
码农总是在搬砖，日复一日，年复一年，有的时候都会麻木。
代码大家都会写，但是把注释写好却是一个技术活。
下面这段话，很好的说明了写好注释的感觉：
注释代码很像清洁你的厕所——你不想干，但如果你做了，这绝对会给你和你的客人带来更愉悦的体验。—— Ryan Campbell
今天给大家聊的就是在Xcode中，代码注释编写小技巧。
Objective-C的代码注释
很久很久以前，在Xcode还可以安装插件的时代，iOSer都通过VVDocument来编写代码注释的。
代码注释的风格一般都是这样的，代码出自IQKeyboardManager/IQBarButtonItem
#import <UIKit/UIBarButtonItem.h> @class NSInvocation; /** IQBarButtonItem used for IQToolbar. */ @interface IQBarButtonItem : UIBarButtonItem /** Boolean to know if it's a system item or custom item */ @property (nonatomic, readonly) BOOL isSystemItem; /** Additional target & action to do get callback action. Note that setting custom target & selector doesn't affect native functionality, this is just an additional target to get a callback. @param target Target object. @param action Target Selector. */ -(void)setTarget:(nullable id)target action:(nullable SEL)action; /** Customized Invocation to be called when button is pressed. invocation is internally created using setTarget:action: method. */ @property (nullable, strong, nonatomic) NSInvocation *invocation; @end复制代码
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的这个中风格了：
我个人建议是：以前代码注释就让它去吧，现在就都是用这个统一风格。
快速修改注释
一个函数写好了，注释也写好，但是有的时候计划没有变化快，函数添加了新的参数，这个注释难道要手动添加？
别急，其实Xcode也为我们提供了快捷方式，我们继续看例子，这个函数我在之前的基础上添加了一个num参数，但是注释还是之前的样子：
cmd+鼠标左键点击，我们可以看到左侧出现了一个菜单，点击Add Documentation
我们需要添加的参数它就来了，这样就可以直接添加注释了。
大家有兴趣可以把菜单的选项都点击试试，也许有意外的惊喜，比如Convert Function to Async，await/async。
参考文档
VVDocumenter
总结
从VVDocument到注释的统一，Xcode一直都在做改进，虽然依旧不尽人意。
但是写好注释，也算是码农的一个基本素养吧，大家加油修炼。
作者：season_zhu
链接：https://juejin.cn/post/7020590213361565726