CodingGuidelinesObjectiveC

Sequence

The first thing in every .h or .m file is the license block (GPL or otherwise)

The next thing are all #include statements

• first comes a block with includes from the project (if any) with a leading comment "Project includes"
• second come all other includes, where includes from the same external source are grouped together in blocks, each block having a header comment that specifies the source

The third thing are forward declarations, with a leading comment "Forward declarations"

The fourth thing, where applicaple are the following things grouped together in blocks, each block having a header comment specifying the block's content

• enumerations
• declarations of helper classes/structs
• constants
• #define statements (try not to use)
• typedefs (try not to use)
• categories

The last thing is either the main class' interface (in the .h file) or implementation (in the .m file).

Methods are implemented in the following order: init, alloc, new, copy, dealloc, other methods.

Example (omitting the license):

// Cocoa
#import <Cocoa/Cocoa.h>

// Forward declarations
@class AceXpanderItem;
@class AceXpanderThread;

// Enumerations
enum AceXpanderItemState
{
   QueuedState     = 0,
   SkipState       = 1,
   ProcessingState = 2,
   AbortedState    = 3,
   SuccessState    = 4,
   FailureState    = 5
};

 
@interface AceXpanderModel : NSObject
{
@private
  NSTableView* m_theTable;
  // ...
}

- (id) init;
  // ...

@end

Documentation

Everything needs to be documented with doxygen documentation blocks.

Doxygen commands are written javadoc-style, using the "@" prefix. Documentation lines should start with the "///" notation:

/// @brief bla bla bla

Documentation blocks should start and end with a distinct separator line. The separator line should start with "//" to prevent doxygen from parsing it.

// -----------------------------------------------------------------------------
/// @brief bla bla bla
///
/// detailed description bla bla bla
// -----------------------------------------------------------------------------

The class documentation is placed in front of the @interface keyword of the class. Because ObjectiveC does not use the "class" keyword, doxygen must be explicitly told that this is a class documentation:

/// @class AceXpanderItem
/// ... 

Doxygen recognizes categories, so we don't have to explicitly identify them:

/// @brief This category declares private methods for the AceXpanderItem class. 
@interface AceXpanderItem(Private)
// ...
@end

Doxygen automatically generates links to methods if they are referenced using the following syntax:

/// @note This is an internal helper method. It is called exactly once per
/// object, from initWithLine:().

Doxygen prints out a warning that methods are undocumented if they appear in declarations of private categories without a grouping around them'. In the following example the method dealloc() is documented, but resetResults() is not:

@interface DGSMonXServer(Private)
/// @name Initialization and deallocation
//@{
- (void) dealloc;
//@}

- (void) resetResults;

Notes:

• Even if warnings are printed, the actual documentation is properly generated
• I encountered the problem with Doxygen 1.5.6, it might be fixed in later versions

Identifier names

Class names start with an uppercase letter and use camel case.

Method names start with a lowercase letter and use camel case.

Member variables (regardless of whether they are instance or class members) use a prefix "m_". A member variable that corresponds to a property uses the property's name (e.g. m_icon).

Simple getter methods use the same name as the property (e.g. icon).

Setter methods use the property name prefixed with "set" (e.g. setIcon).

Miscellaneous

Private methods of a class are declared in a separate category named "Private" in the .m file. For instance:

@interface AceXpanderItem(Private)
// ... methods ...
@end