Objective-C Comment Styles

Objective-C Comment Styles:


A few weeks ago I wrote about Objective-C Indentation Styles. A reader (thanks Joe) commented and suggested a similar post that covered comment formats. That blog post follows…

Interface File Comments

When I create an interface file, here is the basic layout of my comments:

/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*  AboutViewController.h
*
*  Created by John on 6/10/11.
*  Copyright 2011 iOSDeveloperTips.com. All rights reserved.
*
*  Long comments describing this object would go here...
*  ...
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

@interface AboutViewController : UIViewController
{
 UIButton          *backButton;  // Comment here
 NSMutableArray    *queueArray;  // Comment here
 NSMutableArray    *bucketArray;  // Comment here

 //-------------------------------------------------------
 // To describe something in more detail, it would go here
 // searchResultsCount varaible will hold ....
 // questionsResultsCount is calculated by ...
 //-------------------------------------------------------
 int               searchResultsCount;     // Comment here
 int      questionsResultsCount;  // Comment here

}

@end

I’m not sure when it happened, somewhere on the way I moved away from the traditional comment block shown below, I don’t use this for the header or inside the primary code sections. I must of tired of the look and made a small tweak to us ~ and – characters.

/**********************************************************
* To describe something in more detail, it would go here
* searchResultsCount varaible will hold ....
*  questionsResultsCount is calculated by ...
**********************************************************/

Implementation File Comments

At the top of the implementation file, my header looks the same as the interface file. If there is a private interface (see the post Private Methods for more information), I follow the same layout:

/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*  AboutViewController.m
*
*  Created by John on 6/10/11.
*  Copyright 2011 iOSDeveloperTips.com. All rights reserved.
*
*  Long comments describing this class would go here...
*  ...
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

#import "AboutViewController.h"

/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Private interface definitions
*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
@interface AboutViewController(private)
- (BOOL) processSearch:(NSString *)string;
@end

For methods in the class, my comment format looks as follows:

/*---------------------------------------------------------------------------
* Manage button precess events
*--------------------------------------------------------------------------*/
- (void)buttonPressed:(UIButton *)button
{
 // For one line comment
 if (button == backButton)
 {
 }

 //-------------------------------------------------------
 // If more than one line of comments is needed, 
 // I use this format...
 //-------------------------------------------------------
 ...

}

Here is a template of what my code looks like with #pragma marks included:

/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*  AboutViewController.m
*
*  Created by John on 6/10/11.
*  Copyright 2011 iOSDeveloperTips.com. All rights reserved.
*
*  Long comments describing this object would go here...
*  ...
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/

#import "AboutViewController.h"

/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Private interface definitions
*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
@interface AboutViewController(private)
- (BOOL) processSearch:(NSString *)string;
@end

@implementation AboutViewController

#pragma mark - Private Methods

/*---------------------------------------------------------------------------
* This method....
*--------------------------------------------------------------------------*/
- (BOOL) processSearch:(NSString *)string
{
 ... 
}

#pragma mark - Initialization

/*---------------------------------------------------------------------------
* Initialization of ...
* More comments here...
*--------------------------------------------------------------------------*/
- (id) init
{

}

#pragma mark - Event Management

/*---------------------------------------------------------------------------
* Manage button precess events
*--------------------------------------------------------------------------*/
- (void)buttonPressed:(UIButton *)button
{
 // For one line comment
 if (button == backButton)
 {
 }

 //-------------------------------------------------------
 // If more than one line of comments is needed, 
 // I use this format...
 //-------------------------------------------------------
 ...

} 

#pragma mark - Cleanup

/*---------------------------------------------------------------------------
* Cleanup code
*--------------------------------------------------------------------------*/
- (void)dealloc
{
 ...

 [super dealloc];
}

@end

The beauty of using #pragma mark is that within Xcode you can get a nice breakdown of the organization of your code:



You can view this dialog from within Xcode by clicking on the class status bar in the boxed area shown below:

Posting a Comment with Code

Please feel free to post code examples of your comment style. If you would like have your code color highlighted as shown above, using the following format:

<pre lang=”objc”>

your code here

</pre>