iOS -- 注释规范附统一代码块

转载自: http://blog.csdn.net/pingchangtan367/article/details/30041285

http://www.tuicool.com/articles/I3aEJjm

代码的注释经常被人忽略，以至于在后期维护的时候较为困难。我们准备在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回车 变成这样

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

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

tableview是我们经常使用的控件，而使用tableview控件需要自己去实现一些基本的tableview的代理。这些对于每个程序基本上都是大同小异。对于声明property来说也是我们经常需要做的工作。所以我们需要把这些公用的东西总结成代码块，供我们以后的快捷使用。

具体步骤如下：

1.将我们需要重复使用的代码块全部选中拖到下图右下角的libray里面去。

2.这时候会弹出一个对话框需要我们填入一些基本信息

从上到下依次是：

Title

代码片段的标题

Summary

代码片段的描述文字

Platform

可以使用代码片段的平台，有IOS/OS X/All三个选项

Language

可以在哪些语言中使用该代码片段

Completion Shortcut

代码片段的快捷方式，比如XTableView(当我们在工程中输入XTableView时，会自动用我们的代码片段去替换，或者我们直接将其拖入工程中)

Completion Scopes

可以在哪些文件中使用当前代码片段，比如全部位置，头文件中等，当然可以添加多个支持的位置。

最后的一个大得空白区域是对代码片段的效果预览。

最后出现在界面中就是如下：