Using code comments in Xcode 5.0

Code comments are great! We all know this. However, they could be even better with Xcode 5.0. This post will give brief information on how to write proper code comments, so they will appear in autocomplete popups and Quick Help inspector.

Actually, this comment style is pretty typical. There are several keywords, which should be used. So, let’s check those.

We’ll start with constants. You could use /// one-line comments for constants.

/// The answer to the Ultimate Question of Life, the Universe, and Everything.
int const CMTAnswerToUltimateQuestion = 42;

Then, when you start typing constant name, you’ll see this autocomplete suggestion:

It is usually important to have class information available. Let’s add comments to class definition.

/** 
 Sample class.

 @warning Don't use it at home.
 @note This is really sample.
 
 */
@interface CMTSample : NSObject

// ...

@end

Here we use /** multi-line comment start (as oppositite to normal /*). First line of this comment will be used in autocomplete popup.

Other details will be shown when you Option-Click on class name in your code.

As you can see @warning and @note keywords are properly shown in class information. These keywords are also valid for all other code comments.

Another important comment type is method comment. Let’s add comment to method.

/**
 Checks if first parameter is better than second.
 
 @param param1 First parameter.
 @param param2 Second parameter.
 @return YES if first is better, NO if second is better.
 
 @code
 BOOL result = [sample checkIfParameter:@"foo"
                  isBetterThanParameter:@"bar"];
 @endcode

 */
-(BOOL)checkIfParameter:(id)param1 
  isBetterThanParameter:(id)param2;

Here we use the same /** comment start. Again, first line will be shown in autocomplete.

As you can see we you some new keywords – @param and @return (@warning and @note are also valid here). Also, @code and @endcode pair is used to wrap up source code example.

The same is visible in Quick Help inspector page.

You could also add deprecation message to method comment.

/**
 Does some important stuff.
 @see -betterMethod
 */
-(void)deprecatedMethod 
 __attribute__((deprecated("use '-betterMethod'.")));

Here we use two new things. First, @see keyword to mark related method (of course, you can use @see in other comment types as well). And another important step is to mark method with attribute deprecated. You’ll use this after method name and provide message which will be shown in compilation warning and in method information.

But you can use code comments even in method implementation.

-(BOOL)checkIfParameter:(id)param1 
  isBetterThanParameter:(id)param2
{
    /// Holds intermediate result.
    BOOL result = NO;
    
    // ...
    
    return result;
}

This will help to keep information about result variable.

You could also comment block type definitions.

/**
 Sample block declaration.
 
 @param param1 Block's first argument.
 @param param2 Block's second argument.
 
 @return YES if first argument is better, NO if second is better.
 */
typedef BOOL (^CMTSampleBlock)(id param1, id param2);

Comment style is similar to method comments. However, it is important to keep parameter order the same as it is in block definition.

You could also add comments to struct‘s fields, enum values (one-line /// comments will be most efficient in this case). However, these comments do not yet work for definitions of struct or enum itself.

And I’d like to mention one more tool to help out with these comments. Check out VVDocumenter-Xcode project, this could significantly save time on writing these comments. It allows to create function, method comment blocks with all parameters listed. You’ll just have to fill the details. By the time this post was created, this plugin did not support Xcode 5.0 officially, however, I think this would be solved ASAP.