Xcode中程式碼註釋編寫的一些小技巧

2021-10-28 10:00:57

前言

碼農總是在搬磚，日復一日，年復一年，有的時候都會麻木。

程式碼大家都會寫，但是把註釋寫好卻是一個技術活。

下面這段話，很好的說明了寫好註釋的感覺：

註釋程式碼很像清潔你的廁所——你不想幹，但如果你做了，這絕對會給你和你的客人帶來更愉悅的體驗。—— 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的註釋是通過/// 這樣的形式進行編寫的。

分隔符使用的是這種風格：