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

Posted on by

前言

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

代碼大傢都會寫，但是把註釋寫好卻是一個技術活。

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

註釋代碼很像清潔你的廁所——你不想幹，但如果你做瞭，這絕對會給你和你的客人帶來更愉悅的體驗。—— 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一直都在做改進，雖然依舊不盡人意。

但是寫好註釋，也算是碼農的一個基本素養吧，大傢加油修煉。

到此這篇關於Xcode中代碼註釋編寫小技巧的文章就介紹到這瞭,更多相關Xcode代碼註釋編寫內容請搜索WalkonNet以前的文章或繼續瀏覽下面的相關文章希望大傢以後多多支持WalkonNet！

推薦閱讀：