iOS端项目注释规范附统一代码块

代码的注释经常被人忽略，以至于在后期维护的时候较为困难。我们准备在XX项目开始之前制定一套规范的注释体系，致力于达到就算维护人员改变也能快速上手的效果。

1.属性注释

属性注释 使用 /** 注释*/ 的文档注释格式。 这种注释相较于// 注释的优点是此属性可以在后面的引用时，在智能提示的下方显示中文注释

如果你不是在董铂然博客园看到本文请点击查看原文。

例如：

/** 回复率*/
@property(nonatomic,strong)MTPoiCompareM *replyRate;
/** 回复速度*/
@property(nonatomic,strong)MTPoiCompareM *replySpeed;

在之后的调用时可以看到如下效果

并且之后在维护写完的代码时，把光标点到该属性时可以在右侧的quickhelp快速看到此属性的解释。

 

从实际的开发角度来看并不是所有的属性都需要添加注释，只要是属性名能从英文直译或者简单明显的属性 不需要添加属性注释

@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回车 变成这样

 

有时候需要找他们的时候，只需要在项目搜索里敲上就能快速定位

这里也可以设置优先级$$ 或$$$，重点或常出异常的地方都建议标注不需要吝啬。

如果你不是在董铂然博客园看到本文请点击查看原文。 转载请注明出处。