iOS项目OC代码规范 -> 纯文本规范

Cruise_Chan

代码规范

目的是为了组内代码风格统一,加强代码的可读性以及方便维护。这里只做一些非技术方面的代码约束要求。这里大概是参照了AFNetworking以及FaceBook开源代码做了一些tip级别的约束。

Tip1 关于注释

注释是为了说明一个代码模块或者代码段。比如你在github上丢一块代码给大家用。那么就需要你的用户在没有你的情况下能够通过你的注释用好用对你的代码。

哪些地方该写注释

个人认为该写注释的点有SDK类比如网络层、数据仓库、工具类。而像我们经常打交道的VC我觉得写好段注释足矣,在一些比较黑魔法以及比较复杂的业务逻辑写好该写上的注释即可!

怎么写

这里拿了AF的框架来做模板:
图片描述
文件注释结构如下:

  1. 概述 @abstract (可能等价于)

  2. 详述 @discussion

  3. 注意 @warning

属性注释如下:
图片描述
大概描述下干啥用,以及是否有默认值,使用注意事项比如值的范围之类的。

接口注释如下:
图片描述
主要还是参数说明,返回值说明,使用注意事项以及特殊的一些声明。

对于大部分的ViewController.m文件,个人认为只要写好段注释,好比ViewLifecycle、DataSource/Delegate,Actions,IB Methods。以及在关键地方,比如业务逻辑比较复杂或者容易引起Crash的地方需要引起注意的地方补上注释。

Tip2 关于常量

const代替define
主要原因是会define编译器不会帮忙做一层检查。可能在运行时遇到一些Crash!
const使用在.m中对将要使用的一些常量包括字符串,整型,浮点数甚至是结构体进行声明初始化,比如:
图片描述
图片描述

这里补充一点是宏定义还是有使用场景的,比如说断言,或者代码段比如判断iOS版本,比如判断设备类型这种,用宏的主要原因是偷懒,但是需要放在一个文件内做维护,这儿要大家统一维护不然就呵呵了。。
图片描述
图片描述

Tip3 关于代码风格

我觉得这点每个写的习惯不一样但是作为一个Team写的习惯类似一点我觉得还是有点好处的。我们用的是OC,大家知道OC的特点是变量名又臭又长(美其名是说自解释性)。问题来了就是如何进行空格以及大小括号怎么放还有什么时候多敲一个回车的问题,这里盗点文章:

关于在哪里空格

麻了吉就一个字:在关键字后面留空格,在逗号(符号)之后留空格

关于在哪里回车

Preferred:

// blocks are easily readable
[UIView animateWithDuration:1.0 animations:^{
  // something
} completion:^(BOOL finished) {
  // something
}];

Not Preferred:

// colon-aligning makes the block indentation hard to read
[UIView animateWithDuration:1.0
                 animations:^{
                     // something
                 }
                 completion:^(BOOL finished) {
                     // something
                 }];

原因就是OC代码又臭又长,你还冒号对齐,你看代码的时候很容易看飞了,而括号对齐能保证代码不容易看飞!

关于写好一个正常的API接口

Preferred:

- (void)setExampleText:(NSString *)text image:(UIImage *)image;
- (void)sendAction:(SEL)aSelector to:(id)anObject forAllCells:(BOOL)flag;
- (id)viewWithTag:(NSInteger)tag;
- (instancetype)initWithWidth:(CGFloat)width height:(CGFloat)height;

Not Preferred:

-(void)setT:(NSString *)text i:(UIImage *)image;
- (void)sendAction:(SEL)aSelector :(id)anObject :(BOOL)flag;
- (id)taggedView:(NSInteger)tag;
- (instancetype)initWithWidth:(CGFloat)width andHeight:(CGFloat)height;
- (instancetype)initWith:(int)width and:(int)height;  // Never do this.

哥们麻烦放点正常API好不好。一个正常API大概就是汉语里面的主谓宾。还有及物动词不及物动词。。不及物动次记得加上介词。。。。

关于if else应该怎么接

Preferred:

if (user.isHappy) {
  //Do something
} else {
  //Do something else
}

Not Preferred:

if (user.isHappy)
{
    //Do something
}
else {
    //Do something else
}

原因还是因为OC代码相对比较长,这么写结构性更好一点。这个组内达成一个标准就好了。

关于如何在代码块中留回车

图片描述
这里拿的是AF框架做的一个说明,mattt的代码规范我个人还是很推崇的。

Tip4 关于集合类

Preferred:

NSArray *names = @[@"Brian", @"Matt", @"Chris", @"Alex", @"Steve", @"Paul"];
NSDictionary *productManagers = @{@"iPhone": @"Kate", @"iPad": @"Kamal", @"Mobile Web": @"Bill"};
NSNumber *shouldUseLiterals = @YES;
NSNumber *buildingStreetNumber = @10018;

Not Preferred:

NSArray *names = [NSArray arrayWithObjects:@"Brian", @"Matt", @"Chris", @"Alex", @"Steve", @"Paul", nil];
NSDictionary *productManagers = [NSDictionary dictionaryWithObjectsAndKeys: @"Kate", @"iPhone", @"Kamal", @"iPad", @"Bill", @"Mobile Web", nil];
NSNumber *shouldUseLiterals = [NSNumber numberWithBool:YES];
NSNumber *buildingStreetNumber = [NSNumber numberWithInteger:10018];

第一种写法的好处还是简单明了,而且代码更简洁!
字典声明的时候还是应当写的更人性化一点比如:

NSDictionary *productManagers = @{
                                  @"iPhone": @"Kate", 
                                  @"iPad": @"Kamal", 
                                  @"Mobile Web": @"Bill"
                                  };

Tip5 关于OC中的结构体及其属性

我相信很多人喜欢这么写:

CGRect frame = self.view.frame;

CGFloat x = frame.origin.x;
CGFloat y = frame.origin.y;
CGFloat width = frame.size.width;
CGFloat height = frame.size.height;

这样写当然OK了,但是看上去代码很累赘,更倾向这种写法:

CGFloat x = CGRectGetMinX(frame);
CGFloat y = CGRectGetMinY(frame);
CGFloat width = CGRectGetWidth(frame);
CGFloat height = CGRectGetHeight(frame);

多用点C函数可以使代码整洁点。

RW的代码规范中强调了不应该使用结构体声明,其实我觉得挺好,比如:

CGRect frame = (CGRect){ 
                        .origin = CGPointZero, 
                        .size = frame.size 
                        };
CGPoint point = (CGPoint){ 
                          .x = 5, 
                          .y = 6 
                          };                    

我不觉得这种赋值影响可读性。。我觉得可读性会好一点吧....

Tip6 关于段注释

个人不太喜欢在.m中写太多的注释,因为我觉得ViewController中的代码分段大概都是相似的。
这里还是给出AF的段注释来给说明:

#pragma mark -

这个只是一个分割线的效果,一般一个文件有多个@implementation的时候使用

#pragma mark - 段索引

这个是分割线带了概述
截个AF的图来说明:
图片描述
这是说下概述特么不是乱写的,正确的概述写法在按住CMD键鼠标左键点击的时候是可以进行跳转的,规范标准还是以能够跳转为主!

Tip7 关于告警

麻了吉一个字不要留告警,采取任何的手段把告警去掉。。。因为实在看的难受。。。。不要吐槽哥。。

#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wassign-enum"
        if (alpha == kCGImageAlphaNone) {
            bitmapInfo &= ~kCGBitmapAlphaInfoMask;
            bitmapInfo |= kCGImageAlphaNoneSkipFirst;
        } else if (!(alpha == kCGImageAlphaNoneSkipFirst || alpha == kCGImageAlphaNoneSkipLast)) {
            bitmapInfo &= ~kCGBitmapAlphaInfoMask;
            bitmapInfo |= kCGImageAlphaPremultipliedFirst;
        }
#pragma clang diagnostic pop

其他去除告警的关键字("-Wassign-enum")请谷歌。。。去掉告警的时候有必要请同步组内成员!

阅读 2.9k

青楼烟雨
self.blog = [note copy];

技能树点歪了...咋办

726 声望
69 粉丝
0 条评论

技能树点歪了...咋办

726 声望
69 粉丝
文章目录
宣传栏