终极指南：掌握Google Objective-C代码风格规范

终极指南：掌握Google Objective-C代码风格规范

【免费下载链接】styleguideStyle guides for Google-originated open-source projects项目地址: https://gitcode.com/gh_mirrors/st/styleguide

Google Objective-C代码风格规范是一套经过实践验证的编码指南，旨在帮助开发者编写清晰、一致且易于维护的Objective-C代码。作为苹果平台开发的主要语言之一，Objective-C的代码风格直接影响项目的可读性和可维护性。本指南将全面解析Google的Objective-C编码规范，从命名约定到代码格式，助你轻松掌握专业级代码风格。

为什么代码风格规范如此重要？ 🤔

在软件开发中，代码风格规范就像是团队的"语法规则"，它确保所有成员编写的代码具有一致的外观和结构。这不仅降低了代码阅读和理解的难度，还减少了因风格差异导致的沟通成本。对于Objective-C这类动态、面向对象的语言，良好的代码风格尤为重要，因为它直接影响代码的可读性和可维护性。

Google的Objective-C风格规范基于以下核心原则：

• 为读者优化，而非作者：代码的阅读次数远多于编写次数，因此应优先考虑代码的可读性
• 保持一致性：在整个代码库中使用一致的风格，让开发者能够专注于逻辑而非格式
• 与Apple SDK保持一致：遵循苹果的编码习惯，使代码更符合iOS/macOS开发者的预期
• 风格规则应物有所值：每条规则都应有足够的益处，值得开发者记住和遵循

命名约定：让代码自我解释 📛

命名是代码风格中最关键的部分之一。一个好的命名能够让代码自我解释，减少注释的需求。Google的Objective-C命名规范遵循以下原则：

类名和协议名

类名和协议名应使用大写字母开头的驼峰式命名法（PascalCase），并通常使用项目特定的前缀。例如：

// 正确的类名 @interface GTMExample : NSObject // 正确的协议名 @protocol GTMExampleDelegate <NSObject> @end

⚠️ 注意：Apple保留了两字母前缀，因此建议使用至少三个字符的前缀，如GTM（Google Toolbox for Mac）。

方法名

方法名应使用小写字母开头的驼峰式命名法（camelCase），并且应该读起来像一个句子。参数名应清晰描述其用途，并与方法名自然衔接：

// 好的方法名示例 - (void)addTarget:(id)target action:(SEL)action; - (CGPoint)convertPoint:(CGPoint)point fromView:(UIView *)view; - (void)replaceCharactersInRange:(NSRange)aRange withAttributedString:(NSAttributedString *)attributedString;

对于返回布尔值的方法，应使用"is"开头的getter方法名：

// 正确的布尔属性定义 @property(nonatomic, getter=isGlorious) BOOL glorious; // 使用方式 BOOL isGood = object.glorious; // 推荐 BOOL isGood = [object isGlorious]; // 也可以接受

变量名

变量名同样使用小写字母开头的驼峰式命名法。实例变量应添加下划线前缀，全局变量应添加"g"前缀：

// 局部变量 NSString *userName; // 实例变量 NSString *_userName; // 全局变量 NSString *gGlobalUserName;

常量命名应使用驼峰式，并添加项目前缀：

// 正确的常量定义 GTM_EXTERN NSString *const GTMServiceErrorDomain; typedef NS_ENUM(int32_t, GTMServiceError) { GTMServiceErrorQueryResultMissing = -3000, GTMServiceErrorQueryTimedOut = -3001, };

代码组织：构建清晰的结构 🏗️

良好的代码组织能够显著提高代码的可读性和可维护性。Google的Objective-C规范对代码组织有明确的指导原则。

文件结构

每个Objective-C类通常对应两个文件：.h头文件和.m实现文件。文件名应与类名保持一致，并使用适当的扩展名：

• .h: 头文件，包含类声明、协议和公共接口
• .m: 实现文件，包含方法实现和私有代码
• .mm: Objective-C++实现文件

头文件应遵循特定的导入顺序：相关头文件、系统框架头文件、语言库头文件，以及其他依赖项的头文件，每组之间用空行分隔：

// 正确的导入顺序 #import "ProjectX/BazViewController.h" #import <Foundation/Foundation.h> #include <unistd.h> #include <vector> #import "base/mac/FOOComplexNumberSupport"

类接口组织

在.h文件中，类接口的声明顺序应为：属性、类方法、初始化方法，最后是实例方法：

// 正确的接口组织 @interface Foo : NSObject // 属性 @property(nonatomic) Bar *bar; @property(nonatomic, copy) NSDictionary<NSString *, NSNumber *> *attributes; // 类方法/便利构造器 + (instancetype)fooWithBar:(Bar *)bar; // 初始化方法 - (instancetype)initWithBar:(Bar *)bar NS_DESIGNATED_INITIALIZER; // 实例方法 - (BOOL)doWorkWithBlah:(NSString *)blah; @end

实现文件组织

在.m文件中，应将重写的NSObject方法放在最前面，包括init、copyWithZone:和dealloc等方法：

// 正确的实现组织 @implementation Foo { NSString *_string; } // 初始化方法 - (instancetype)initWithBar:(Bar *)bar { self = [super init]; if (self) { _bar = [bar copy]; _string = [[NSString alloc] initWithFormat:@"hi %d", 3]; } return self; } // 类方法 + (instancetype)fooWithBar:(Bar *)bar { return [[self alloc] initWithBar:bar]; } // 实例方法 - (BOOL)doWorkWithBlah:(NSString *)blah { return NO; } @end

初始化和内存管理：避免常见陷阱 🚫

Objective-C的初始化和内存管理是容易出错的地方，Google规范提供了明确的指导来避免这些问题。

明确指定初始化方法

每个类应明确标识其指定初始化方法，并使用NS_DESIGNATED_INITIALIZER宏进行标注：

// 正确的初始化方法声明 - (instancetype)initWithBar:(Bar *)bar NS_DESIGNATED_INITIALIZER; // 实现指定初始化方法 - (instancetype)initWithBar:(Bar *)bar { self = [super init]; if (self) { _bar = [bar copy]; } return self; } // 其他初始化方法应调用指定初始化方法 - (instancetype)init { return [self initWithBar:nil]; }

避免在初始化和dealloc中发送消息

在初始化方法和dealloc中应避免调用实例方法，因为此时对象可能处于不稳定状态：

// 推荐的方式 - (instancetype)init { self = [super init]; if (self) { _bar = 23; // 直接访问实例变量 } return self; } // 不推荐的方式 - (instancetype)init { self = [super init]; if (self) { self.bar = 23; // 调用属性访问器 [self sharedMethod]; // 调用实例方法 } return self; }

正确处理可变对象

对于可能为可变类型的对象（如NSString、NSArray等），应在设置属性时进行复制，以避免外部修改：

// 正确的属性声明 @property(nonatomic, copy) NSString *name; @property(nonatomic, copy) NSSet<FilterThing *> *filters; // 正确的初始化方式 - (instancetype)initWithName:(NSString *)name filters:(NSSet<FilterThing *> *)filters { self = [super init]; if (self) { _name = [name copy]; // 复制字符串 _filters = [filters copy]; // 复制集合 } return self; }

注释：提升代码可理解性 📝

注释是代码风格中不可或缺的部分，良好的注释能够极大地提高代码的可理解性。

文件注释

每个文件应在开头包含版权声明和文件内容描述：

// Copyright 2023 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. /** * A sample class demonstrating good Objective-C style. All interfaces, * categories, and protocols MUST be commented. */ @interface Foo : NSObject ... @end

声明注释

每个类、属性、方法都应有明确的注释，描述其用途、参数和返回值：

/** * Convenience creation method. * See -initWithBar: for details about @c bar. * * @param bar The string for fooing. * @return An instance of Foo. */ + (instancetype)fooWithBar:(Bar *)bar; /** * Initializes and returns a Foo object using the provided Bar instance. * * @param bar A string that represents a thing that does a thing. */ - (instancetype)initWithBar:(Bar *)bar NS_DESIGNATED_INITIALIZER;

实现注释

对于复杂的实现逻辑，应添加注释解释其工作原理：

// Set the property to nil before invoking the completion handler to // avoid the risk of reentrancy leading to the callback being // invoked again. CompletionHandler handler = self.completionHandler; self.completionHandler = nil; handler();

代码格式：美观与规范 🎨

一致的代码格式能够提高代码的可读性，减少阅读时的认知负担。

缩进和空格

使用2个空格进行缩进，不使用制表符。方法参数应垂直对齐冒号：

// 正确的缩进和参数对齐 - (void)doSomethingWithFoo:(GTMFoo *)theFoo rect:(NSRect)theRect interval:(float)theInterval { // 2个空格缩进 if (theFoo) { [self processFoo:theFoo]; } }

条件语句

条件语句的格式应保持一致，即使单行也建议使用大括号：

// 推荐的条件语句格式 if (hasBaz) { foo(); } else { bar(); } // 单行条件也可以接受，但不推荐 if (hasSillyName) LaughOutLoud();

方法调用

方法调用应要么全部在一行，要么每个参数单独一行并对齐冒号：

// 单行方法调用 [myObject doFooWith:arg1 name:arg2 error:arg3]; // 多行方法调用，对齐冒号 [myObject doFooWith:arg1 name:arg2 error:arg3];

常见陷阱和最佳实践 💡

Objective-C有一些独特的特性和陷阱，了解这些能够帮助你编写更健壮的代码。

避免BOOL类型陷阱

BOOL在某些平台上被定义为signed char，可能有YES(1)和NO(0)之外的值。因此，在转换其他类型为BOOL时应使用条件表达式：

// 正确的方式 - (BOOL)isBold { return ([self fontTraits] & NSFontBoldTrait) ? YES : NO; } // 错误的方式 - (BOOL)isBold { return [self fontTraits] & NSFontBoldTrait; // 可能返回非1的值 }

不要直接比较BOOL值与YES：

// 推荐 if (great) { ... } // 不推荐 if (great == YES) { ... }

使用轻量级泛型提高类型安全

Xcode 7及以上版本支持Objective-C轻量级泛型，可以提高集合的类型安全：

// 正确使用泛型 @property(nonatomic, copy) NSArray<Location *> *locations; @property(nonatomic, copy, readonly) NSSet<NSString *> *identifiers; NSMutableArray<MyLocation *> *mutableLocations = [otherObject.locations mutableCopy];

避免使用+new方法

不要使用NSObject的+new方法，而应使用+alloc和-init方法：

// 推荐 Foo *foo = [[Foo alloc] init]; // 不推荐 Foo *foo = [Foo new];

总结：编写专业的Objective-C代码 🚀

遵循Google的Objective-C代码风格规范，不仅能够提高代码的可读性和可维护性，还能帮助你避免常见的陷阱和错误。无论是命名约定、代码组织，还是内存管理和注释风格，每一个细节都影响着代码的质量。

记住，代码风格的最终目标是为了让代码更容易被人理解。在实际开发中，除了遵循这些规范外，还应保持代码的简洁和逻辑的清晰。只有这样，才能编写出真正专业、高质量的Objective-C代码。

希望本指南能够帮助你掌握Google的Objective-C代码风格规范，提升你的代码质量和开发效率！如果你想深入了解更多细节，可以查阅项目中的完整规范文档：objcguide.md。

【免费下载链接】styleguideStyle guides for Google-originated open-source projects项目地址: https://gitcode.com/gh_mirrors/st/styleguide