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:
Const autocomplete

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.
Class autocomplete

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

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.
Method 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.
Method usage definition

The same is visible in Quick Help inspector page.
Method QuickHelp

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.
Deprecated definition

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.
Method variable autocomplete

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.
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.

Advertisements

One thought on “Using code comments in Xcode 5.0

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s