/**

              注释内容
*/

///在对文件、类、函数进行注释时推荐使用多行注释，在函数体内对代码块进行注释时，使用单行注释

/**
 *  @brief  
 *  @param
 *  @return
 **/
 在brief中需要写明函数的主要功能、注意事项
 在param中需要写明函数的变量类型、变量的作用
 在return中需要写明函数的返回类型、返回值的作用
 如有其他需要说明的地方，可以在@return后面添加新项。如
 /**
 *  @brief  
 *  @param
 *  @return
 *  @warning
 **/

/**
 *  @brief      上传图片。上传成功后会自动将图片放入缓存，缓存的key为图片的url
 *  @param      UIImage，需要上传的图片
 *  @return     void
 *  @blocks
 *              success:返回的NSDictionary中包含服务器的response信息，包括图片id（id）,url(url),宽度(width),高度(height)。使用括号中的名称从NSDictionary中获取。
 *              failed:返回error
 **/

  - (id)getDelegate;    //avoid
  - (id)delegate;       //good

如:message_private_at_button_bg_normal.png

如:MessagePrivateAtsomebody

如:
//NSString 为要扩展的类名, GTMStringParsingAdditions为类别名
@interface NSString (GTMStringParsingAdditions)
        - (NSString *)gtm_foobarString;
        @end

        @interface FoobarViewController ()
        @property(nonatomic, retain) NSView *dongleView;
        - (void)performLayout;
        @end

如:
if (!error) {
    return success;
}

如:
@interface NYTSection: NSObject

@property (nonatomic) NSString *headline;

@end

应尽量避免下面的方式:

@interface NYTSection : NSObject {
    NSString *headline;
}

如:
self.imgView.backgroundColor = [UIColor black];

而尽量避免:

_imgView.backgroundColor = [UIColor black];

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

不恰当:
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 *ZIPCode = [NSNumber numberWithInteger:10018];

如：
CGRect frame = self.view.frame;

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

不恰当：
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;

如：
typedef NS_ENUM(NSInteger, NYTAdRequestState) {
    NYTAdRequestStateInactive,
    NYTAdRequestStateLoading
};

如：
if (!someObject) {
}

if (isAwesome)

if (![someObject boolValue])

不恰当：
if (someObject == nil) {
}

if ([someObject boolValue] == NO)

if (isAwesome == YES) // Never do this.

@property (assign, getter=isEditable) BOOL editable;

如：
(instancetype)sharedInstance {
   static id sharedInstance = nil;

   static dispatch_once_t onceToken;
   dispatch_once(&onceToken, ^{
      sharedInstance = [[self alloc] init];
   });

   return sharedInstance;
}

//#pragma mark Properties

@dynamic someProperty;

- (void)setCustomProperty:(id)value {}

#pragma mark Lifecycle

+ (id)objectWithThing:(id)thing {}
- (id)init {}

#pragma mark Drawing

#pragma mark UItableView delegate

#pragma mark UITableView datasource

- (void)drawRect:(CGRect) {}

#pragma mark Another functional grouping

#pragma mark GHSuperclass

- (void)someOverriddenMethod {}

#pragma mark NSCopying

- (id)copyWithZone:(NSZone *)zone {}

#pragma mark NSObject

- (NSString *)description {}

如:
if (button.enabled) {
    // Stuff
} else if (otherButton.enabled) {
    // Other stuff
} else {
    // More stuf
}

如:
switch (something.state) {
    case 0: {
        // Something
        break;
    }

    case 1: {
        // Something
        break;
    }

    case 2:
    case 3: {
        // Something
        break;
    }

    default: {
        // Something
        break;
    }
}

如:
- (void)doSomethingWithString:(NSString *)theString {
  ...
}

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

如:
- (void)doSomethingWith:(GTMFoo *)theFoo
                   rect:(NSRect)theRect
               interval:(float)theInterval {
  ...
}

             longKeyword:(NSRect)theRect
       evenLongerKeyword:(float)theInterval
                   error:(NSError **)theError {
          ...
}

[myObject doFooWith:arg1 name:arg2 error:arg3];

如:
[myObject doFooWith:arg1
               name:arg2
              error:arg3];

如:
[myObj short:arg1
          longKeyword:arg2
    evenLongerKeyword:arg3
                error:arg4];

如:
@interface MyClass : NSObject{
 @public
 …
 @private
}
@end

如:
@interface MyProtocoledClass : NsObject<NSWindowDelegate> {
 @private
  id<MyFancyDelegate> _delegate;
}
-  (void)setDelegate:(id<MyFancyDelegate>)aDelegate;
@end

在一行的情况
如:
[operation setCompletionBlock:^{ [self onOperationDone]; }];

//block 在新的行里，需要缩进四个空格
[operation setCompletionBlock:^{
      [self.delegate newDataAvailable];
}];

dispatch_async(_fileIOQueue, ^{
      NSString* path = [self sessionFilePath];
      if (path) {
        // ...
      }
});

//有参数的block,|(SessionWindow *window)|与|{|之间有一个空格
如:
[[SessionService sharedService]
    loadWindowWithCompletionBlock:^(SessionWindow *window) {
        if (window) {
          [self windowDidLoad:window];
        } else {
          [self errorLoadingWindow];
        }
    }];

//block 中有参数且不能在一行中显示
//要行与行之间要相对有四个空格
[[SessionService sharedService]
      loadWindowWithCompletionBlock:
            ^(SessionWindow *window) {
                   if (window) {
                     [self windowDidLoad:window];
                   } else {
                     [self errorLoadingWindow];
                   }
            }];

//很长的block可以被定义不在一行里
void (^largeBlock)(void) = ^{
    // ...
};
[_operationQueue addOperationWithBlock:largeBlock];