Thursday, September 21, 2006

[Tip] Pragma Mark ( Organizing your source code )

Well I've just been frustrated today by several things going on including getting a wireless ethernet adapter to work so to get my mind off everything I thought i'd just post an easy quick tip before going to bed. One thing many new people aren't aware of in Xcode is the Pragma mark in source code. Pragma mark is simply a way to organize your methods in the method list pop up button in Xcode (as were using it here, though there are more uses of pragma mark on other platforms/IDE's.) On a default project you might see something like this Now on a very small project with only a few methods that's not really hard to go through. The problem is as soon as you have a ton of methods in any one file it's difficult to do down through the list and find the one method your looking for, and even if you don't have a ton of methods you should use pragma mark to help you organize your code for yourself and (if your working with anybody else) your team. With pragma marks you can do 2 types of labels

#pragma mark -
which will simply put a horizontal line spacer in your code. (Warning! - When using this you cannot have a space after the "-" otherwise Xcode assumes you are making a text label (below in next example) and won't insert a horizontal spacer line.) And there is
#pragma mark label name
which will add a label in bold to your method pop up list. When using this one be very simple and to the point so it's obvious of where the method your looking for is at. So if we add some of those pragma marks to the source code like
#pragma mark Initialization Methods #pragma mark -
to the source code when we want to add a label you can make the list now look like this Now again this example is small and that second label doesn't make sense where it is (just wanted to put a 2nd one in there), but when you start getting into bigger and bigger projects it's practically mandatory to add pragma mark labels and spacers to your source code. Do yourself a favor and from the start of working on a cocoa project use pragma marks to help you organize your code. Remember that Xcode reads methods on any given file you are viewing/editing from top to bottom and will put the methods and labels on that popup list as it encounters them. It may not matter where you put your methods in your file for compiling them, but it will matter where your methods are if you intend to use the pragma mark labels.

14 comments:

Anonymous said...

The issue with #pragma mark is that as late as XCode 2.2, the source parser is buggy and some marks will not appear.

Quality and Apple are 2 different things these days...

Massive said...

I've never had that problem with #pragma mark in Xcode, FWIW.

A couple of points, though:

1. TextMate also supports #pragma mark, and there's a snippet for it (In a C/C++/ObjC document, type 'mark' and press tab).

2. Because pragmas are implementation-specific, you should surround #pragma mark declarations with "#if 0". The editor will still see the mark, but the compiler will ignore it.

毅樂 said...

I got it !
thx so much!
: )

David said...

Interesting, thanks

Anonymous said...

In order to see the organized list, you have to go to XCode Preferences | Code Sense
and uncheck Sort list alphabetically

Adrian said...

You don't have to protect pragmas with #if 0: the standard says that if the compiler doesn't recognize it, then the pragma will be ignored. There's a small chance that "#pragma mark" will be interpreted by the compiler to mean something other than what we're talking about here, but that would be pretty retarded... mark is a well-known pragma, and any such compiler would quickly run into problems.

(I know this post is ancient, but it's a top result in Google for "pragma mark".)

Pavel said...

Hi Colin. Thanks for the article. It's better to keep classes small but I'll use @pragma mark to separate private and public methods.

Jeff Chang said...

Thanks for the tip!

Steve Neal said...

That's a great post - I'm just learning Objective-C and iPhone programming at the moment. Posts like this are gold dust when you come across something this cryptic in example code.

Anonymous said...

Now if only XCode would do code folding around #pragma mark lines...

Sachin Palewar said...

Thanks. Nice quick, easy tip.

Anonymous said...

@Anonymous

You can always add curly braces at any place in your code to create a foldable block.

aprilShowers said...

Thank you, was wondering what that was for...

petoi said...

I like putting a dash before and after the title. This puts a line before and after which looks even nicer in the pull down.

#pragma mark - MyClass -

 
...