Xcode中代码注释编写小技巧

代码大家都会写，但是把注释写好却是一个技术活。

下面这段话，很好的说明了写好注释的感觉：

注释代码很像清洁你的厕所——你不想干，但如果你做了，这绝对会给你和你的客人带来更愉悦的体验。—— 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。