### 关于iOS代码注释的统一规范
在iOS开发中，代码注释是维护和管理项目不可或缺的一部分。本文档旨在介绍一套iOS应用开发中的代码注释规范，这不仅有助于提高团队内部的协作效率，还能确保代码的清晰度和可读性。
#### 一、Objective-C代码注释规范
Objective-C作为iOS开发的主要语言之一，其注释规范至关重要。在日常开发过程中，为了保持一致性和避免风格混杂带来的视觉污染，应遵循固定的注释格式。以下是具体的规范：
##### 1.1 单行注释
单行注释通常用于简短描述。推荐使用`///`作为前缀，这种格式同时被appledoc和doxygen识别为简要描述，具有很高的兼容性。
- **格式推荐**：`/// 简要描述。`
- **注意点**：
1. 文本最好以英文句号（.）结尾，这有助于明确文本的结束，并减少乱码时可能出现的换行符丢失问题。
2. 避免连续多行使用`///`，因为doxygen默认会将其视为详细描述而非简要描述。虽然可以通过配置调整来解决这个问题，但这违背了简要描述的初衷。
##### 1.2 多行注释
当需要提供更详细的描述时，可以使用多行注释。推荐格式为：
```objective-c
/**
详细描述。
*/
```
这种格式同样被appledoc和doxygen所支持，适合于需要详细解释的地方。
##### 1.3 行尾注释（仅doxygen）
在对枚举、结构体等类型成员进行注释时，为了使内容更加紧凑，可以使用行尾注释。遗憾的是，目前只有doxygen支持行尾注释，而appledoc不支持。doxygen支持以下四种行尾注释：
1. `<**/`：appledoc不支持，会被当作下一项的注释；doxygen支持，并能根据英文句号自动区分简要描述与详细描述。
2. `/*!<`：appledoc不支持，会被当作下一项的注释；doxygen支持，但会全部当作详细描述处理。
3. `</**`：appledoc不支持，会被当作下一项的注释；doxygen支持。
4. `<!/<`：appledoc会忽略，doxygen支持。
为了避免appledoc将行尾注释误解为下一项的注释，建议使用第四种方式。
##### 1.4 类（协议、分类）的注释
对于类（协议、分类），一般只需要写简要描述即可，此时可以使用单行注释：
```objective-c
/// 文档A。
@interface DocA : NSObject
```
如果需要更详细的描述，则可以使用多行注释：
```objective-c
/**
文档B的详细描述。
*/
@interface DocB : NSObject
```
##### 1.5 属性的注释
属性的注释最好使用单行注释：
```objective-c
/// 数值属性。
@property (nonatomic, assign) NSInteger num;
```
如果需要详细描述，则使用多行注释：
```objective-c
/**
属性的详细描述。
*/
@property (nonatomic, strong) NSString *str;
```
##### 1.6 方法的注释
对于没有参数和返回值的方法，可以使用单行注释：
```objective-c
/// 简单方法。
- (void)someMethod;
```
对于有参数或返回值的方法，则需要使用多行注释：
```objective-c
/**
带整数参数的方法。
@param value 参数。
@return 返回值。
*/
- (int)someMethodByInt:(int)value;
```
其中`@param`用于描述参数，`@return`用于描述返回值。
##### 1.7 其他指令
除了基本的注释格式外，还可以在方法注释中加入其他指令，例如：
```objective-c
/**
@brief 带字符串参数的方法。
@param value 值。
@return 返回value。
@exception NSException 可能抛出的异常。
@see someMethod
@see someMethodByInt:
@warning 警告：appledoc中显示为蓝色背景，Doxygen中显示为红色竖条。
@bug 缺陷：appledoc中显示为黄色背景，Doxygen中显示为绿色竖条。
*/
- (NSString *)someMethodByStr:(NSString *)value;
```
- `@exception`：用于描述可能抛出的异常。
- `@see`：用于指向其他相关方法或类。
- `@warning`：用于提醒开发者注意潜在的问题。
- `@bug`：用于标记已知的缺陷。
##### 1.8 代码文本与代码块
- **代码文本**：有时需要在一段文字中引用一小段代码，这时可以使用反引号（`）将这段代码包裹起来。例如：
```objective-c
/**
引用短代码，如`someMethodByStr:`.
*/
```
- **代码块**：如果需要在注释中放置多行代码，则可以使用代码块的形式。例如：
```objective-c
/**
示例代码:
- (void)someMethod {
// 这里是示例代码
}
*/
```
通过以上规范，可以有效地提高iOS开发中代码的可读性和一致性，为团队协作打下坚实的基础。
