iOS端項目注釋規範附統一代碼塊,ios注釋
代碼的注釋經常被人忽略,以至於在後期維護的時候較為困難。我們準備在XX項目開始之前制定一套規範的注釋體系,致力於達到就算維護人員改變也能快速上手的效果。
1.屬性注釋
屬性注釋 使用 /** 注釋*/ 的文檔注釋格式。 這種注釋相較於// 注釋的優點是此屬性可以在後面的引用時,在智能提示的下方顯示中文注釋
如果你不是在董鉑然部落格園看到本文請點擊查看原文。
例如:
/** 回複率*/@property(nonatomic,strong)MTPoiCompareM *replyRate;/** 回複速度*/@property(nonatomic,strong)MTPoiCompareM *replySpeed;
@property(nonatomic,copy)NSString *name;@property(nonatomic,assign)float avgScore;@property(nonatomic,assign)int dealid;@property(nonatomic,assign)float price;@property(nonatomic,assign)int feedbackNum;
①通過屬性名稱無法快速且明顯的瞭解該用途的屬性必須添加註釋,如index到底是誰的index?但是存在下列特性的屬性必須添加註釋
②類似於狀態的標記可能有0,1,2三種情況的要將幾種情況的注釋一起寫入
③屬性名稱的英文直譯無法說清時
上面特點與下面的代碼逐條對應:
/** 頂部分類的下標*/@property(nonatomic,assign)int index;/** 項目類型 1是團購 2是券*/@property(nonatomic,assign)int type;/** 本行業平均資料*/@property(nonatomic,copy)NSString *cateValue;
這裡插播一下引入代碼塊的步驟。這裡統一一屬性注釋的代碼塊為 /** <#注釋#>*/ 快速鍵為xx
2.引入代碼塊的步驟
1.將橘色部分複製到項目中的任意一個位置。裡面部分會自動縮成一個塊
然後選中這些 拖入 右下角的代碼塊中。
拖入後鬆手會顯示設定框,按要求設定
然後點擊done, 這個代碼塊就會存在Xcode中。
使用代碼塊的好處就是可以在項目中敲出快速鍵加斷行符號就能馬上出現自己預置的代碼並且,按tab鍵可以快速切換到一個個小塊進行編寫
3.方法集注釋
系統有一個內建的方法集注釋代碼塊
但是這個是不帶分隔線的,如果要加分隔線 還需要在後面加上 mark - 再跟上注釋,有點麻煩
使用後可以達到如下效果
現統一一下,給出代碼塊
#pragma mark - **************** <#輸入注釋#> 快速鍵為mark
之所以中間用****拉長是為了避免與下面的注釋一起重疊在前面不易觀看
所有類的資料來源方法 或 代理方法的方法集前面必須加上一行方法集注釋來做分隔。(代碼要求將某個類的幾個代理方法應該寫在一起)
4.普通注釋
在項目中的某個地方的邏輯可能比較複雜或者是核心思想的代碼,這種地方應加上一些注釋作為標註,也利於自己維護代碼,利於之後別人接手代碼。
例如:
現統一一下,給出代碼塊
// ------<#單行注釋#> 快速鍵為gg
5.優先順序注釋
這個重點注釋可以自訂, 我給出我標註重點的注釋的代碼塊如下,也建議大家可以統一,便於查看
// $$$$$ 快速鍵為dd
一般寫在一個大項目中經常需要跳過去修改的地方,用法是在這行代碼後面快速敲上dd斷行符號 變成這樣
有時候需要找他們的時候,只需要在項目搜尋裡敲上就能快速定位
這裡也可以設定優先權$$ 或$$$,重點或常出異常的地方都建議標註不需要吝嗇。
如果你不是在董鉑然部落格園看到本文請點擊查看原文。 轉載請註明出處。