阅读 3115
Xcode中代码注释编写小技巧

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 - 这个是一个分割符
复制代码

image.png

需要注意的是这个-非常的重要,通过这个-,在查看代码的时候,可以生成分隔线,让代码结构看的更为清晰。

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: - 绑定
复制代码

image.png

Swift中的//MARK:这个-也是起到生成分隔线的作用。

Objective-C和Swift的注释风格现在已经统一

如果你现在通过alt+cmd+/在OC和Swift中编写注释的时候,就会发现现在的注释都变成了Swift的这个中风格了:

image.png

image.png

我个人建议是:以前代码注释就让它去吧,现在就都是用这个统一风格。

快速修改注释

一个函数写好了,注释也写好,但是有的时候计划没有变化快,函数添加了新的参数,这个注释难道要手动添加?

别急,其实Xcode也为我们提供了快捷方式,我们继续看例子,这个函数我在之前的基础上添加了一个num参数,但是注释还是之前的样子:

image.png

cmd+鼠标左键点击,我们可以看到左侧出现了一个菜单,点击Add Documentation

image.png

我们需要添加的参数它就来了,这样就可以直接添加注释了。

image.png

大家有兴趣可以把菜单的选项都点击试试,也许有意外的惊喜,比如Convert Function to Async,await/async。

参考文档

VVDocumenter

总结

从VVDocument到注释的统一,Xcode一直都在做改进,虽然依旧不尽人意。

但是写好注释,也算是码农的一个基本素养吧,大家加油修炼。

我们下期见。

欢迎在评论区讨论,掘金官方将在掘力星计划活动结束后,在评论区抽送100份掘金周边,抽奖详情见活动文章。

文章分类
iOS
文章标签