iOS注释艺术

0.各种注释

#pragma mark - pragma mark
//MARK:MARK:
//TODO:TODO
//FIXME:FIXME
//???:???

代码的注释经常被人忽略,以至于在后期维护的时候较为困难。我们准备在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.方法集注释
系统有一个自带的方法集注释代码块

  #pragma <#arguments#>

但是这个是不带分隔线的,如果要加分隔线 还需要在后面加上 mark - 再跟上注释,有点麻烦

现统一一下,给出代码块

#pragma mark - **************** <#输入注释#>  快捷键为mark

之所以中间用****拉长是为了避免与下面的注释一起重叠在前面不易观看

所有类的数据源方法 或 代理方法的方法集前面必须加上一行方法集注释来做分隔。(代码要求将某个类的几个代理方法应该写在一起)

4.普通注释
在项目中的某个地方的逻辑可能比较复杂或者是核心思想的代码,这种地方应加上一些注释作为标注,也利于自己维护代码,利于之后别人接手代码。
现统一一下,给出代码块

// ------<#单行注释#>  快捷键为gg

5.优先级注释
这个重点注释可以自定义, 我给出我标注重点的注释的代码块如下,也建议大家可以统一,便于查看

// $$$$$ 快捷键为dd

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

这里也可以设置优先级$$ 或$$$,重点或常出异常的地方都建议标注不需要吝啬。
6.使用特殊注释

// TODO:// FIXME:// !!!:// ???:

在XCode 3,我们可以用类似这样的注释来方便我们标记需要修改的部分。
在XCode 4,需要做如下设置,才可以在编译后的Warning里面看到我们标记的TODO, FixME等:
进入项目属性设置那个页面 选择一个Target选择Build Phases标签 点击右下角的Add Build Phase展看上面刚出现那一栏Run Script,输入以下内容

KEYWORDS="TODO:|FIXME:|\\?\\?\\?:|\\!\\!\\!:"find "${SRCROOT}" 
−*name*"∗.*h*"−*or*−*name*"∗.*m*"
 -print0 | xargs -0 egrep --with-filename --line-number --only-matching "($KEYWORDS).*\\$" | perl -p -e "s/($KEYWORDS)/ warning: \\$1/"

当然你也可以自己定义一些特殊注释.

推荐阅读更多精彩内容

  • Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具(例如配置管理,服务发现,断路器,智...
    卡卡罗2017阅读 121,073评论 16 134
  • Android 自定义View的各种姿势1 Activity的显示之ViewRootImpl详解 Activity...
    passiontim阅读 157,663评论 24 688
  • 喜欢周杰伦13年了。 喜欢安东尼8年了。 喜欢刘同5年了。 …… 很多人,很多物,很多事,喜欢上就再也没变过,只会...
    小薇子阅读 170评论 3 1
  • 走一条未曾走过的路,然后遗忘 学不会皱眉,体会不到心酸, 动不了许多情,演不了情深义重 走很多的路,然后心静成一片...
    七禾希阅读 54评论 0 1
  • 学校安排了家访工作。而且强调要拍照上传。造假也得有几分像。办公室里,大家就此事苦恼怎么操作这件事?最后大家认为在微...
    独孤草原狼阅读 34评论 0 0