Google Objective-C 代码风格指南解析

Google Objective-C 代码风格指南解析

styleguide 项目地址: https://gitcode.com/gh_mirrors/st/styleguide

前言

Objective-C 作为 C 语言的面向对象扩展，是 Apple 平台应用开发的主要语言之一。Google 的 Objective-C 代码风格指南为开发者提供了一套经过实践检验的编码规范，旨在提高代码的可读性、一致性和可维护性。本文将深入解析这份指南的核心要点。

核心原则

1. 为读者优化而非作者

代码的生命周期往往很长，阅读代码的时间远超过编写时间。因此，Google 风格指南强调：

• 代码应易于阅读、维护和调试
• 在代码中加入适当的注释和提示
• 避免过于复杂的写法，即使它可能让编写更便捷

2. 保持一致性

一致性是代码风格的核心价值：

• 在整个代码库中采用统一的风格
• 减少风格争论，让开发者专注于更重要的问题
• 便于自动化工具处理代码

3. 与 Apple SDK 保持一致

遵循 Apple SDK 的 Objective-C 使用方式：

• 采用 Apple 推荐的惯用法
• 对于有缺陷的语言特性，可以限制或禁止使用

4. 规则的性价比

每条风格规则的收益必须大于工程师记忆它的成本。这解释了为什么有些潜在问题没有被纳入规范——因为它们极少发生。

代码示例解析

头文件示例

// 良好的头文件示例
#import <Foundation/Foundation.h>

@class Bar;

/**
 * 展示良好Objective-C风格的示例类。
 * 所有接口、分类和协议都必须有注释。
 */
@interface Foo : NSObject

/** 保留的Bar对象 */
@property(nonatomic) Bar *bar;

/** 当前绘图属性 */
@property(nonatomic, copy) NSDictionary<NSString *, NSNumber *> *attributes;

/**
 * 便捷创建方法。
 * @param bar 用于foo操作的字符串
 * @return Foo实例
 */
+ (instancetype)fooWithBar:(Bar *)bar;

/**
 * 使用提供的Bar实例初始化和返回Foo对象
 * @param bar 代表某个事物的字符串
 */
- (instancetype)initWithBar:(Bar *)bar NS_DESIGNATED_INITIALIZER;
@end

实现文件示例

// 良好的实现文件示例
#import "Shared/Util/Foo.h"

@implementation Foo {
  /** 用于显示"hi"的字符串 */
  NSString *_string;
}

+ (instancetype)fooWithBar:(Bar *)bar {
  return [[self alloc] initWithBar:bar];
}

- (instancetype)init {
  return [self initWithBar:nil];
}

- (instancetype)initWithBar:(Bar *)bar {
  self = [super init];
  if (self) {
    _bar = [bar copy];
    _string = [[NSString alloc] initWithFormat:@"hi %d", 3];
  }
  return self;
}
@end

命名规范详解

1. 基本命名原则

• 名称应尽可能描述性强但不过长
• 避免非标准缩写
• 遵循标准的Objective-C命名规则

良好示例：

int numberOfErrors = 0;
NSDate *applicationLaunchDate;

应避免的示例：

int w;
int nerr;

2. 包容性语言

• 使用包容性术语
• 避免可能冒犯他人的词汇
• 使用性别中立语言

3. 文件命名

• 文件名应反映其包含的类名（包括大小写）
• 扩展名规范：
  • .h：头文件
  • .m：实现文件
  • .mm：Objective-C++实现文件

分类文件应包含被扩展的类名，如：NSString+Utils.h

4. 前缀使用

为避免命名冲突：

• 类、协议、全局函数和常量应使用前缀
• 前缀应以大写字母开头，后跟一个或多个大写字母/数字
• 建议使用至少3个字符的前缀（Apple保留两字母前缀）

示例：

GTM_EXTERN NSString *GTMExampleErrorDomain;
@protocol GTMExampleDelegate <NSObject>
@end

5. 方法命名规范

• 方法名应像句子一样可读
• 参数名应与方法名自然衔接
• 避免不必要的连词

良好示例：

- (void)addTarget:(id)target action:(SEL)action;
- (CGPoint)convertPoint:(CGPoint)point fromView:(UIView *)view;

访问器方法应与其属性同名，不加"get"前缀：

- (id)delegate;  // 良好
- (id)getDelegate;  // 应避免

布尔属性应使用is前缀，但属性名本身省略is：

@property(nonatomic, getter=isEnabled) BOOL enabled;
BOOL good = object.enabled;  // 良好
BOOL good = [object isEnabled];  // 良好
BOOL good = object.isEnabled;  // 应避免

6. 变量命名

• 局部变量：小写字母开头，混合大小写（myLocalVariable）
• 实例变量：前导下划线（_myInstanceVariable）
• 全局变量：g前缀（gGlobalVariable）

常量应使用混合大小写：

static const int kFileCount = 12;
static NSString *const kUserKey = @"kUserKey";

枚举值应扩展typedef名称：

typedef NS_ENUM(int32_t, DisplayTinge) {
  DisplayTingeGreen = 1,
  DisplayTingeBlue = 2,
};

类型与声明规范

1. 方法声明顺序

@interface声明中建议顺序：

1. 属性
2. 类方法（以便捷构造器开头）
3. 初始化方法
4. 实例方法

2. 局部变量

• 在最小作用域内声明
• 初始化时声明
• 避免声明未使用的变量

总结

Google的Objective-C风格指南强调代码的可读性、一致性和可维护性。通过遵循这些规范，开发者可以：

1. 编写出更易于理解和维护的代码
2. 减少团队间的风格争议
3. 提高代码质量
4. 与Apple的编码实践保持一致

记住，好的代码风格不是限制创造力的枷锁，而是提高协作效率的工具。当团队中的每个人都遵循相同的规范时，整个项目的可维护性将大幅提升。

styleguide 项目地址: https://gitcode.com/gh_mirrors/st/styleguide