KVOController代码规范：遵循Objective-C编码标准
【免费下载链接】KVOController Simple, modern, thread-safe key-value observing for iOS and OS X. 项目地址: https://gitcode.***/gh_mirrors/kv/KVOController
1. 概述
KVOController是一个用于iOS和OS X的简单、现代、线程安全的键值观察框架。本文档旨在介绍KVOController项目中遵循的Objective-C编码标准，帮助开发者编写符合项目规范的代码。
2. 头文件规范
2.1 版权信息
所有头文件应包含版权信息，如FBKVOController.h所示：
/**
Copyright (c) 2014-present, Facebook, Inc.
All rights reserved.
This source code is licensed under the BSD-style license found in the
LICENSE file in the root directory of this source tree. An additional grant
of patent rights can be found in the PATENTS file in the same directory.
*/
2.2 宏定义
宏定义应使用大写字母，单词之间用下划线分隔。如FBKVOController.h中的FBKVOKeyPath和FBKVOClassKeyPath宏：
#define FBKVOKeyPath(KEYPATH) \
@(((void)(NO && ((void)KEYPATH, NO)), \
({ const char *fbkvokeypath = strchr(#KEYPATH, '.'); NSCAssert(fbkvokeypath, @"Provided key path is invalid."); fbkvokeypath + 1; })))
#define FBKVOClassKeyPath(CLASS, KEYPATH) \
@(((void)(NO && ((void)((CLASS *)(nil)).KEYPATH, NO)), #KEYPATH))
2.3 类和协议声明
类和协议声明应使用清晰的命名，遵循驼峰命名法。如FBKVOController.h中声明的FBKVOController类：
@interface FBKVOController : NSObject
3. 接口设计规范
3.1 属性声明
属性声明应明确指定原子性、读写权限和内存管理策略。如NSObject+FBKVOController.h中的属性：
@property (nonatomic, strong) FBKVOController *KVOController;
@property (nonatomic, strong) FBKVOController *KVOControllerNonRetaining;
3.2 方法命名
方法命名应清晰描述其功能，遵循Objective-C的命名规范。如FBKVOController.h中的初始化方法：
+ (instancetype)controllerWithObserver:(nullable id)observer;
- (instancetype)initWithObserver:(nullable id)observer retainObserved:(BOOL)retainObserved NS_DESIGNATED_INITIALIZER;
4. 实现规范
4.1 代码缩进和格式
代码应使用4个空格缩进，方法之间空一行，逻辑块之间适当空行。如FBKVOController.h中的方法实现结构。
4.2 注释规范
方法和属性应添加详细的注释，说明其功能、参数和返回值。如FBKVOController.h中observe方法的注释：
/**
@abstract Registers observer for key-value change notification.
@param object The object to observe.
@param keyPath The key path to observe.
@param options The NSKeyValueObservingOptions to use for observation.
@param block The block to execute on notification.
@discussion On key-value change, the specified block is called. In order to avoid retain loops, the block must avoid referencing the KVO controller or an owner thereof. Observing an already observed object key path or nil results in no operation.
*/
- (void)observe:(nullable id)object keyPath:(NSString *)keyPath options:(NSKeyValueObservingOptions)options block:(FBKVONotificationBlock)block;
5. 错误处理规范
使用NSCAssert进行断言检查，确保关键条件满足。如FBKVOController.h中FBKVOKeyPath宏的断言：
NSCAssert(fbkvokeypath, @"Provided key path is invalid.");
6. 示例代码
6.1 观察单个键路径
[self.KVOController observe:object keyPath:@"property" options:NSKeyValueObservingOptionNew block:^(id observer, id object, NSDictionary *change) {
// 处理变化
}];
6.2 观察多个键路径
[self.KVOController observe:object keyPaths:@[@"property1", @"property2"] options:NSKeyValueObservingOptionNew block:^(id observer, id object, NSDictionary *change) {
// 处理变化
}];
7. 参考资料
- 官方文档：README.md
- 头文件定义：FBKVOController.h、NSObject+FBKVOController.h
- 示例代码：Examples/
【免费下载链接】KVOController Simple, modern, thread-safe key-value observing for iOS and OS X. 项目地址: https://gitcode.***/gh_mirrors/kv/KVOController
