Xcode 中代碼注釋編寫小技巧

↓推薦關(guān)注↓

前言

碼農(nóng)總是在搬磚，日復(fù)一日，年復(fù)一年，有的時候都會麻木。

代碼大家都會寫，但是把注釋寫好卻是一個技術(shù)活。

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

注釋代碼很像清潔你的廁所——你不想干，但如果你做了，這絕對會給你和你的客人帶來更愉悅的體驗?！?Ryan Campbell

今天給大家聊的就是在Xcode中，代碼注釋編寫小技巧。

Objective-C的代碼注釋

很久很久以前，在Xcode還可以安裝插件的時代，iOSer都通過VVDocument來編寫代碼注釋的。

代碼注釋的風(fēng)格一般都是這樣的，代碼出自IQKeyboardManager/IQBarButtonItem

#import?

@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的注釋是通過/** */這樣的形式進(jìn)行編寫的。

分隔符使用的是這種風(fēng)格：

#pragma?mark?-?這個是一個分割符

需要注意的是這個-非常的重要，通過這個-，在查看代碼的時候，可以生成分隔線，讓代碼結(jié)構(gòu)看的更為清晰。

Swift的代碼注釋

隨著Swift語言發(fā)布，在Swift中編寫注釋的風(fēng)格就所有不同了：

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)
????}
????
????///?這是一個例子函數(shù)
????///?-?Parameter?arg:
????///?-?Parameter?argument:?傳入Int類型的參數(shù)
????///?-?Returns:?返回Int類型的參數(shù)
????public?func?afunction(argument:?Int)?->?Int?{
????????return?argument
????}
}

Swift的注釋是通過///這樣的形式進(jìn)行編寫的。

分隔符使用的是這種風(fēng)格：

//MARK:?-?綁定

Swift中的//MARK:這個-也是起到生成分隔線的作用。

Objective-C和Swift的注釋風(fēng)格現(xiàn)在已經(jīng)統(tǒng)一

如果你現(xiàn)在通過alt+cmd+/在OC和Swift中編寫注釋的時候，就會發(fā)現(xiàn)現(xiàn)在的注釋都變成了Swift的這個中風(fēng)格了：

個人建議是：以前代碼注釋就讓它去吧，現(xiàn)在就都是用這個統(tǒng)一風(fēng)格。

快速修改注釋

一個函數(shù)寫好了，注釋也寫好，但是有的時候計劃沒有變化快，函數(shù)添加了新的參數(shù)，這個注釋難道要手動添加？

別急，其實Xcode也為我們提供了快捷方式，我們繼續(xù)看例子，這個函數(shù)我在之前的基礎(chǔ)上添加了一個num參數(shù)，但是注釋還是之前的樣子：

cmd+鼠標(biāo)左鍵點擊，我們可以看到左側(cè)出現(xiàn)了一個菜單，點擊Add Documentation

我們需要添加的參數(shù)它就來了，這樣就可以直接添加注釋了。

大家有興趣可以把菜單的選項都點擊試試，也許有意外的驚喜，比如Convert Function to Async，await/async。

參考文檔

VVDocumenter（https://github.com/onevcat/VVDocumenter-Xcode）

總結(jié)

從VVDocument到注釋的統(tǒng)一，Xcode一直都在做改進(jìn)，雖然依舊不盡人意。

但是寫好注釋，也算是碼農(nóng)的一個基本素養(yǎng)吧，大家加油修煉。

轉(zhuǎn)自：掘金 season_zhu

https://juejin.cn/post/7020590213361565726

推薦閱讀??點擊標(biāo)題可跳轉(zhuǎn)

1、iPhone 12 到 iPhone17的猜測

2、iOS 15 內(nèi)置原生壁紙下載

3、iOS 15 如何讓 App 啟動更快？

看完本文有收獲？請分享給更多人

關(guān)注「 iOS大全 」加星標(biāo)，關(guān)注 iOS 動態(tài)

點贊和在看就是最大的支持??