Objective-C 代码规范文档

1. 命名规范

1.1 基本原则

• 清晰性：名称应准确描述变量/方法的功能
• 一致性：遵循 Apple 的命名约定
• 前缀要求：类名使用 3 个大写字母前缀（如 ABCViewController）
• 避免缩写：除非是广泛接受的缩写（如 URL, JSON）

1.2 类与协议

// 类名使用大驼峰式
@interface ABCDataManager : NSObject

// 协议名使用大驼峰式，行为协议可加 -ing 后缀
@protocol ABCDataManagerDelegate <NSObject>

1.3 方法命名

// 方法名使用小驼峰式，动词开头
- (void)loadUserDataWithCompletion:(ABCCompletionBlock)completion;

// 布尔方法使用 is/has/can 前缀
- (BOOL)isDataAvailable;

1.4 变量与属性

// 属性使用小驼峰式
@property (nonatomic, copy) NSString *userName;

// 实例变量使用下划线前缀（自动合成）
@synthesize userName = _userName;

// 常量使用小驼峰式
static const NSTimeInterval kAnimationDuration = 0.3;

2. 代码格式

2.1 空格与缩进

• 使用 4 个空格 缩进（非 Tab）
• 方法大括号不换行
• 运算符两侧加空格

- (void)exampleMethod {
    if (self.isActive) {
        CGFloat result = a + b * c;
        [self calculate:result];
    }
}

2.2 方法声明与调用

// 声明：返回类型与方法名在同一行
- (void)configureViewWithModel:(ABCModel *)model 
                   completion:(void (^)(BOOL))completion {
    // ...
}

// 调用：多参数时对齐冒号
[object doSomethingWith:parameter1
             parameter:parameter2
             parameter:parameter3];

2.3 条件语句

if (condition) {
    // ...
} else if (anotherCondition) {
    // ...
} else {
    // ...
}

switch (variable) {
    case 1: {
        // 多行代码用大括号
        break;
    }
    case 2:
        // 单行代码
        break;
    default:
        break;
}

3. 属性与内存管理

3.1 属性特性

@property (nonatomic, copy) NSString *name;          // 字符串使用 copy
@property (nonatomic, weak) id<ABCDelegate> delegate; // 委托使用 weak
@property (nonatomic, assign) NSInteger count;        // 基本类型使用 assign
@property (nonatomic, strong) NSArray *items;         // 对象使用 strong

3.2 内存管理最佳实践

// 在 init 和 dealloc 中直接访问实例变量
- (instancetype)init {
    if (self = [super init]) {
        _dataArray = [NSArray array];
    }
    return self;
}

- (void)dealloc {
    [[NSNotificationCenter defaultCenter] removeObserver:self];
}

// 其他地方使用属性访问
- (void)updateData {
    self.dataArray = newData;
}

4. Block 使用规范

4.1 Block 类型定义

typedef void (^ABCCompletionBlock)(NSData *data, NSError *error);

4.2 避免循环引用

__weak typeof(self) weakSelf = self;
[self fetchDataWithCompletion:^{
    __strong typeof(weakSelf) strongSelf = weakSelf;
    [strongSelf processData];
}];

5. 并发处理

5.1 GCD 使用规范

// 创建串行队列
dispatch_queue_t serialQueue = dispatch_queue_create("com.example.serial", DISPATCH_QUEUE_SERIAL);

// 并发队列与栅栏块
dispatch_barrier_async(concurrentQueue, ^{
    // 写操作
});

// 一次性执行
+ (instancetype)sharedInstance {
    static dispatch_once_t onceToken;
    static id sharedInstance;
    dispatch_once(&onceToken, ^{
        sharedInstance = [[self alloc] init];
    });
    return sharedInstance;
}

6. 类与协议设计

6.1 类扩展隐藏私有内容

// .m 文件中
@interface ABCDataManager ()
@property (nonatomic, strong) NSMutableArray *internalData;
- (void)privateProcessingMethod;
@end

6.2 协议设计规范

@protocol ABCDataFetcher <NSObject>
@required
- (void)fetchData;

@optional
- (void)handleError:(NSError *)error;
@end

7. 错误处理

7.1 NSError 使用规范

NSError *error = nil;
if (![self validateData:data error:&error]) {
    if ([self.delegate respondsToSelector:@selector(handleError:)]) {
        [self.delegate handleError:error];
    }
    return;
}

8. 代码组织

8.1 文件结构

ABCViewController.h
ABCViewController.m
ABCViewController+Layout.h   // 分类
ABCViewController+Layout.m

8.2 #pragma mark 分组

@implementation ABCViewController

#pragma mark - Lifecycle

- (void)viewDidLoad {
    [super viewDidLoad];
}

#pragma mark - UI Actions

- (IBAction)submitButtonTapped:(id)sender {
}

#pragma mark - ABCDataManagerDelegate

- (void)dataDidUpdate {
}

@end

9. 最佳实践

9.1 集合类处理

// 使用字面量语法
NSArray *items = @[item1, item2, item3];
NSDictionary *config = @{@"key": value};

// 安全遍历
[array enumerateObjectsUsingBlock:^(id obj, NSUInteger idx, BOOL *stop) {
    // 处理对象
}];

9.2 相等性判断

- (BOOL)isEqual:(id)object {
    if (self == object) return YES;
    if (![object isKindOfClass:[self class]]) return NO;
    
    ABCModel *other = (ABCModel *)object;
    return [self.identifier isEqual:other.identifier];
}

- (NSUInteger)hash {
    return [self.identifier hash];
}

10. 注释与文档

10.1 文档注释

/// 加载用户数据
/// @param userId 用户唯一标识
/// @param completion 完成回调，返回数据或错误
- (void)loadUserData:(NSString *)userId 
         completion:(ABCCompletionBlock)completion;

10.2 代码注释

// 使用 // 进行行注释
/*
 多行注释
 用于复杂逻辑说明
 */

实施建议：

1. 使用 Clang-Format 自动格式化代码
2. 在 Xcode 中开启静态分析（Analyze）
3. 定期进行代码审查
4. 使用前缀避免符号冲突
5. 重要方法添加单元测试

版本控制：

• 本规范版本：1.0
• 最后更新日期：2023年10月15日

良好的编码规范是团队协作的基石，应结合项目特点灵活调整并严格执行。