Archive for February, 2010

Don’t Get Lost! Tag your Comments!

Project Management, like version control, is something every developer should always be doing at some level in their work…period.  Regardless of the size and scope of a project, basic task management keeps things moving in the right direction.  However, I’m not saying that this should require some elaborate process either.  Oftentimes, a complex process can drive efficiency into the floor.  There is a common standard among major Integrated Development Environments (IDEs) that allows a developer to do a little bit of their own “in situ” project management using code comments…and I believe that this feature is drastically under-utilized.

These comment tags are recognized by IDEs and can be used to quickly and effectively build simple To-Do lists to help you complete all your objectives, or even just place markers in the source so you remember where to go back to.  Because of the scope of my recent work, and of this blog, my examples will focus on Xcode and Eclipse.  However, the general principle applies to many others out there.

Creating Comment Tags

There are two common keywords that work across IDEs: TODO and FIXME.  By placing comments like the following in your code, your on your way to managing what you need to do next, and where you need to do it:

// TODO: Add a method to handle incoming floats
// FIXME: The app crashes here when releasing the object

Placing these at the location where they are relevant will save you time and headache in situations like these:

  • Picking up where you left off the day before
  • Marking a location in a file when you have to move to another while tracing
  • Fleshing out stubs (start with a list of TODO comment before you write any code)

While this is a nice and simple procedure to follow, its the IDEs reaction to these that really makes them useful…

Xcode

Xcode recognizes the following tag styles in comments:

// TODO:
// FIXME:
// ???:
// !!!:

Note the colons on the primary tags, because Xcode needs them.  Notice also that there are two more generic tags that can be used to further subdivide your task listings (??? and !!!).  With these tags in your code, Xcode helps you out by placing markers in the file listing (where you also find your #pragma mark statements).

Each tag is organized underneath the method where it is located.  You may also choose to group your tags at the beginning of the file, as was done in the example above.  This cleans up the listing and puts all the tags in one place, but you don’t gain the ability to click and be transported to the relevant location.  It’s up to you!

Eclipse

Eclipse recognizes the following tag styles in comments:

// TODO
// FIXME
// XXX

Note that Eclipse provides one more tag to further assist you in subdividing your tasks (XXX, which must be capitalized).  With these tags placed in comments, Eclipse does three things for you:

  • Include a blue marker on the scroll bar in the source view (in the same location as yellow markers for warnings and red markers for errors)
  • Include a clipboard task marker on the left bar in the source view
  • Provide a Tasks View where you can view all active tags in all the files of your project at one glance.

The scroll bar marker feature is what makes using TODO or XXX tags as placeholders useful.  You can tag a location, move down to a method you need to finish, and then pop back to where your tag is.

The Tasks View may not be visible by default in Eclipse, but can be brought up from the Window -> Show View -> Other… menu (there is an option called Tasks).  Here you will be presented with a table that points out each tag and its location.  FIXME tags are marked with the exclamation point by default as well.

For the same reasons that single developers should always use version control, basic management of your tasks is crucial to happy and sane development.  In my opinion, this is a great start and it doesn’t get any simpler than this.

iPhone Tip: Info Button Woes

Today’s tip is a simple solution to a common problem.  The fix for this problem is all over the internet, but none of the places I visited seemed to give the whole story, they only revealed a piece of the puzzle (sorry for the cliché).  All of us who use the iPhone with any frequency have seen the info button used in onr place or another.  This cute little circle with a lower-case “i” inside is a popular widget used by Apple to denote a way to gain access to details like application settings.

When developers start using this widget in their own code, often two very distinct symptoms pop up instantaneously as soon as they get their app onto a real device:

  1. Often I have to tap the button 3 or more times before it detects the event!
  2. Sometimes (usually when debugging) I tap the button and it recognizes the event seconds later!

This can be a frustrating problem to troubleshoot, especially for a new developer, and is exacerbated by the actual root of the problem…the button is just too darn small!

The Solution

So what do we do about this?  Well, many of us would intuitively try to open up Interface Builder and increase the widget size.  However, Apple has fixed the button’s frame to 18×19 pixels and it cannot be changed through IB.  So for those of us who like to do as much UI layout in IB as possible, we have to roll up our sleeves and write a little code.  Don’t be scared, there isn’t much to it:

The Code

As I mentioned, IB grays out the frame of the Info Button, but it isn’t really a fixed value; you can declare a new frame and apply it to the button in code.  First, choose the amount by which you want to increase the button (I usually use 50 pixels), and let’s call that value “G”.  The following code will shift and grow your frame around the info button.


1
2
3
4
5
CGRect newInfoButtonRect = CGRectMake(infoButton.frame.origin.x-(G/2),
          infoButton.frame.origin.y-(G/2),
          infoButton.frame.size.width+G,
          infoButton.frame.size.height+G);
[infoButton setFrame:newInfoButtonRect];

Code adapted from iPhone SDK Examples.

The Location

So where does this code need to be?  In the UIViewController that handles the button.  I’ve had varying degrees of success putting this code in different methods, but putting it into viewDidLoad: seems to yield the best results.  Don’t forget that the info button must be defined as a property in the UIViewController so we can work with it.  The example below assumes you define your layouts in IB, so the button is also an IBOutlet:

UIViewControllerSubclass.h


1
2
3
4
5
6
@interface ... {
    UIButton *infoButton
}
...
@property (nontatomic,retain) IBOutlet UIButton *infoButton;
@end

UIViewControllerSubclass.m


1
2
3
4
5
6
7
8
...
- (void)viewDidLoad {
    CGRect newInfoButtonRect = CGRectMake(infoButton.frame.origin.x-25, infoButton.frame.origin.y-25,
          infoButton.frame.size.width+50, infoButton.frame.size.height+50);
    [infoButton setFrame:newInfoButtonRect];
    [super viewDidLoad];
}
...

Also, don’t forget to connect the newly created outlet to the Info Button you have defined in IB. With your button’s frame freshly enlarged, give the app another try and see how much easier it is to properly trigger the info button with a real finger!