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.

Tags: ,

Comments are closed.