# 3.1. 代码注释格式

当需要的时候，注释应该被用来解释为什么特定代码做了某些事情。所使用的任何注释必须保持最新，否则就删除掉。

通常应该避免一大块注释，代码就应该尽量作为自身的文档，只需要隔几行写几句说明。这并不适用于那些用来生成文档的注释。

## **文件注释**

采用Xcode自动生成的注释格式，修改部分参数：

```
//
//  AppDelegate.m
//  LeFit
//
//  Created by Zhang Wen on 15-3-22.
//  Copyright (c) 2015 Appscomm LLC. All rights reserved.
//
```

其中**项目名称**、**创建人**、**公司/组织版权**需要填写正确。

## **import注释**

如果有一个以上的 import 语句，就对这些语句进行[分组](https://ashfurrow.com/blog/structuring-modern-objective-c/#grouping-import-statements)。每个分组的注释是可选的。

注：对于模块使用[`@import`](http://clang.llvm.org/docs/Modules.html#using-modules)语法。

```
    // Frameworks
    @import QuartzCore;

    // Models
    #import "NYTUser.h"

    // Views
    #import "NYTButton.h"
    #import "NYTUserView.h"
```

## **方法注释**

~~采用~~[~~Javadoc~~](https://en.wikipedia.org/wiki/Javadoc)~~的格式，可以使用Xcode插件~~[~~VVDocumenter-Xcode~~](https://github.com/onevcat/VVDocumenter-Xcode)~~快速添加，只需输入~~`///`~~即可~~

Xcode 8后请使用自带扩展插件，快捷键`Option`＋`Command`＋`／`

```
/**
 <#Description#>

 @param tableView <#tableView description#>
 @param section <#section description#>
 @return <#return value description#>
 */
- (NSString *)tableView:(UITableView *)tableView titleForHeaderInSection:(NSInteger)section {
    return [self.familyNames objectAtIndex:section];
}
```

## **代码块注释**

单行的用`//`+`空格`开头，多行的采用`/* */`注释

## **TODO注释**

TODO 很不错, 有时候注释确实是为了标记一些未完成的或完成的不尽如人意的地方, 这样一搜索就知道还有哪些活要干, 日志都省了。

格式：`//TODO: 说明`

```
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    //TODO: 增加初始化
    return YES;
}
```

## 常用规范

```
- 运算符前后前后各一个空格
- *号紧贴属性名，和类名之间隔一个空格
NSString *text = @"hello world";

- 括号前后各一个空格
- 属性修饰符和前面的,隔一个空格
@property (nonatomic, strong) UITableView *tableView;

- 当参数过长的时候，没个参数占用一行，且按照冒号对齐。
- 在声明类方法或者实例方法的时候，“+”或者“-”和返回值之间保留一个空格，
且返回值和方法名的第一个字母之间不要留空格。
-(void)doSomethingWithName:(NSString *)name
                      rect:(CGRect)rect;

- 注释一般放在.h，.m文件尽量减少注释
单行的用//+空格开头，多行的采用/* */注释
//TODO:  用来注释没有完成的功能
#warning 用来标记自己的debug修改，以免遗漏

哪里需要注释:
1. 在某个变量、属性、或者方法不能够直接从名字得知其用途时。 
2. 区分代码区时(在常量文件和控制器类的.h文件和.m文件里)。 
3. 在不相关的业务处理交叉点。
4. 文件的基本信息
5. 有疑惑的地方(FIXME)
6. 未完成或者待优化的地方。(#waring //TODO:) 
7. 声明枚举时应该对每个值说明。
8. 修改别人代码的时候。
9. 编写API时，一般需要对所有的接口和属性带上注释
注释需要注意:
1. 不要为了注释而注释，请只在关键点注释
2. 划分代码块最好的方式不一定是注释，有时候使用空行也可以达到很好的效果。

-  初始化
在初始化方法中，不要将变量初始化为“0”或“nil”，那是多余的，
 内存中所有的新创建的对象(isa除外)都是0，所以不需要重复初始化 为 “0”或“nil”;
对nil的检查
仅在有业务逻辑需求时检查nil,而非为了防止崩溃。

- 组件的创建，应该使用代码块或者懒加载的方式（我习惯用代码块）

- 建议项目统一使用Masonry的方式布局。不允许出现直接设置frame的情况。
xib的使用，尽量减少拉约束的情况
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://alexcode2.gitbook.io/ios-development-guidelines/gui-fan/3.-dai-ma-ge-shi-gui-fan/31.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.