// GOOD:

#import <Foundation/Foundation.h>

@class Bar;

/**
 * 一个展示良好 Objective-C 风格的示例类。所有接口、
 * 分类和协议（即：头文件中所有非平凡的顶层声明）
 * 必须添加注释。注释也必须紧邻其所文档化的对象。
 */
@interface Foo : NSObject

/** 被持有的 Bar。 */
@property(nonatomic) Bar *bar;

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

/**
 * 便捷创建方法。
 * 关于 @c bar 的详情请参见 -initWithBar:。
 *
 * @param bar 用于 foo 操作的字符串。
 * @return 一个 Foo 实例。
 */
+ (instancetype)fooWithBar:(Bar *)bar;

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

/**
 * 使用 @c blah 执行某些工作。
 *
 * @param blah
 * @return 如果工作完成返回 YES；否则返回 NO。
 */
- (BOOL)doWorkWithBlah:(NSString *)blah;

@end

// GOOD:

#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];
    _attributes = @{
      @"color" : UIColor.blueColor,
      @"hidden" : @NO
    };
  }
  return self;
}

- (BOOL)doWorkWithBlah:(NSString *)blah {
  // 应在此处完成工作。
  return NO;
}

@end