Class Initialization

The initialize  class method gives you a place to have some code executed once, lazily, before any other method of the class is invoked. It is typically used to set the version numbers of classes (see Versioning and Compatibility).

The runtime sends initialize to each class in an inheritance chain, even if it hasn’t implemented it; thus it might invoke a class’s initialize method more than once (if, for example, a subclass hasn’t implemented it). Typically you want the initialization code to be executed only once. One way to ensure this happens is to use dispatch_once():

+ (void)initialize {

    static dispatch_once_t onceToken = 0;

    dispatch_once(&onceToken, ^{

        // the initializing code

    }

}

You should never invoke the initialize method explicitly. If you need to trigger the initialization, invoke some harmless method, for example:

[NSImage self];

Designated Initializers

A designated initializer is an init method of a class that invokes an init method of the superclass. (Other initializers invoke the init methods defined by the class.) Every public class should have one or more designated initializers. As examples of designated initializers there is NSView’s initWithFrame: and NSResponder’s init method. Where init methods are not meant to be overridden, as is the case with NSString and other abstract classes fronting class clusters, the subclass is expected to implement its own.

Designated initializers should be clearly identified because this information is important to those who want to subclass your class. A subclass can just override the designated initializer and all other initializers will work as designed.

When you implement a class of a framework, you often have to implement its archiving methods as well: initWithCoder: and encodeWithCoder:. Be careful not to do things in the initialization code path that doesn’t happen when the object is unarchived. A good way to achieve this is to call a common routine from your designated initializers and initWithCoder: (which is a designated initializer itself) if your class implements archiving.

Error Detection During Initialization

A well-designed initialization method should complete the following steps to ensure the proper detection and propagation of errors:

1. Reassign self by invoking super’s designated initializer.

2. Check the returned value for nil, which indicates that some error occurred in the superclass initialization.

3. If an error occurs while initializing the current class, release the object and return nil.

Listing 1 illustrates how you might do this.

Listing 1  Error detection during initialization

- (id)init {

    self = [super init];  // Call a designated initializer here.

    if (self != nil) {

        // Initialize object  ...

        if (someError) {

            [self release];

            self = nil;

        }

    }

    return self;

}

Framework Version

When the presence of a new feature or bug fix isn’t easily detectable with runtime tests, you should provide developers with some way to check for the change. One way to achieve this is to store the exact version number of the framework and make this number accessible to developers:

• Document the change (in a release note, for instance) under a version number.

• Set the current version number of your framework and provide some way to make it globally accessible. You might store the version number in your framework’s information property list (Info.plist) and access it from there.

Keyed Archiving

If the objects of your framework need to be written to nib file, they must be able to archive themselves. You also need to archive any documents that use the archiving mechanisms to store document data.

You should consider the following issues about archiving:

• If a key is missing in an archive, asking for its value will return nil, NULL, NO, 0, or 0.0, depending on the type being asked for. Test for this return value to reduce the data that you write out. In addition, you can find out whether a key was written to the archive.

• Both the encode and decode methods can do things to ensure backwards compatibility. For instance, the encode method of a new version of a class might write new values using keys but can still write out older fields so that older versions of the class can still understand the object. In addition, decode methods might want to deal with missing values in some reasonable way to maintain some flexibility for future versions.

• A recommended naming convention for archive keys for framework classes is to begin with the prefix used for other API elements of the framework and then use the name of the instance variable. Just make sure that names cannot conflict with the names of any superclass or subclass.

• If you have a utility function that writes out a basic data type (in other words, a value that isn’t an object), be sure to use a unique key. For example, an “archiveRect” routine that archives a rectangle should take a key argument and either use the given key or, if it writes out multiple values (for instance, four floats), it should append its own unique bits to the provided key.

• Archiving bitfields as-is can be dangerous due to compiler and endianness dependencies. You should archive them only when, for performance reasons, a lot of bits need to be written out, many times. See Bitfields for a suggestion.

Constant Data

For performance reasons, it is good to mark as constant as much framework data as possible because doing so reduces the size of the __DATA segment of the Mach-O binary. Global and static data that is not const ends up in the __DATA section of the __DATA segment. This kind of data takes up memory in every running instance of an application that uses the framework. Although an extra 500 bytes (for example) might not seem so bad, it might cause an increment in the number of pages required—an additional four kilobytes per application.

You should mark any data that is constant as const. If there are no char * pointers in the block, this will cause the data to land in the __TEXT segment (which makes it truly constant); otherwise it will stay in the __DATA segment but will not be written on (unless prebinding is not done or is violated by having to slide the binary at load time).

You should initialize static variables to ensure that they are merged into the __data section of the __DATA segment as opposed to the __bss section. If there is no obvious value to use for initialization, use 0, NULL, 0.0, or whatever is appropriate.

Bitfields

Using signed values for bitfields, especially one-bit bitfields, can result in undefined behavior if code assumes the value is a boolean. One-bit bitfields should always be unsigned. Because the only values that can be stored in such a bitfield are 0 and -1 (depending on the compiler implementation), comparing this bitfield to 1 is false. For example, if you come across something like this in your code:

BOOL isAttachment:1;

int startTracking:1;

You should change the type to unsigned int.

Another issue with bitfields is archiving. In general, you shouldn’t write bitfields to disk or archives in the form they are in, as the format might be different when they are read again on another architecture, or on another compiler.

Memory Allocation

In framework code, the best course is to avoid allocating memory altogether, if you can help it. If you need a temporary buffer for some reason, it’s usually better to use the stack than to allocate a buffer. However, stack is limited in size (usually 512 kilobytes altogether), so the decision to use the stack depends on the function and the size of the buffer you need. Typically if the buffer size is 1000 bytes (or MAXPATHLEN) or less, using the stack is acceptable.

One refinement is to start off using the stack, but switch to a malloc’ed buffer if the size requirements go beyond the stack buffer size. Listing 2 presents a code snippet that does just that:

Listing 2  Allocation using both stack and malloc’ed buffer

#define STACKBUFSIZE (1000 / sizeof(YourElementType))

 YourElementType stackBuffer[STACKBUFSIZE];

 YourElementType *buf = stackBuffer;

 int capacity = STACKBUFSIZE;  // In terms of YourElementType

 int numElements = 0;  // In terms of YourElementType

while (1) {

    if (numElements > capacity) {  // Need more room

        int newCapacity = capacity * 2;  // Or whatever your growth algorithm is

        if (buf == stackBuffer) {  // Previously using stack; switch to allocated memory

            buf = malloc(newCapacity * sizeof(YourElementType));

            memmove(buf, stackBuffer, capacity * sizeof(YourElementType));

        } else {  // Was already using malloc; simply realloc

            buf = realloc(buf, newCapacity * sizeof(YourElementType));

        }

        capacity = newCapacity;

    }

    // ... use buf; increment numElements ...

  }

  // ...

  if (buf != stackBuffer) free(buf);