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>

  1. Try this one instead. Really makes it pop in the dialog:

    #pragma mark – === Cleanup === –

    Note the – at the start and end of the line.

  2. Thanks for the template of code. Its helpful to see all the comments as they would be in a .m file.

  3. I like your style a lot. I’m going to copy it

  4. Nice tips! I always find myself struggling to get a good and clean look in my classes.

    I used to write code in actionscript and, sometimes, I still find it hard to change my comments layout due to some Objective-C changes.

  5. Speaking of the class status bar, if you click on the bar and then start typing, the list will be filtered based on what you type. It’s useful for large classes with many properties, methods, etc.

  6. Why not use Doxygen comments? Then your comments can be your API documentation as well as just looking pretty.

Comments are closed.