Using a Debugging Mark can be one of the easier, yet more powerful tools in your programmer’s tool kit. Yet many developers have never heard of a Debugging Mark.
A Debugging Mark is nothing more than a special sequence of characters that are inserted into the code to call attention to that area. You should use it to mark places in the code that need to be reviewed or changed at a later time, but before any release. For example, if you modify several constants while testing, add the Debugging Mark and a few words at each change as a helpful reminder to undo those changes before the release. If a procedure is only “partially-written” – say you have written the main path through the code, but error handling has been left out – you should add a Debugging Mark plus a note to finish the procedure.
When modifying code, a distraction from the process may produce a bad result. One of my “best” uses of the Debugging Mark occurs while I am working on one problem, but I notice something “funny”. I quickly drop a Debugging Mark at the spot in the code with a note saying “this doesn’t seem right” and then continue on. Minimal distraction has occurred and I can continue to focus on the original problem. At a later time, I search for debugging marks for code issues that need to be resolved.
When writing status reports for my clients, I usually note the number of Debugging Marks that remain in the code. It is a metric for how much clean-up remains to be completed. (I carefully explain that although the majority of Debugging Marks indicate minor issues, a few may require significant time to review and make code adjustments.)
To be useful, the Debugging Mark must be a sequence of characters that would never occur in code. Personally, I use ???? (four question marks) inside a comment. It is easy to add and easy to find using a text search.
It should be obvious that a project should have exactly one sequence of characters for the Debugging Mark even if there is more than one programmer. When code is constructed by several developers, I suggest that the Debugging Mark be followed by the initials of the developer who added the mark to the code. Never allow the programming team to create multiple Debugging Marks. Inevitably one or more will be missed during code reviews.
I offer a few final thoughts. Debugging Marks are not meant to be long-term additions to the code; they should be thought of as sticky notes. Never do a code release that includes a Debugging Mark. (I learned this lesson the hard way.) Leaving a Debugging Mark in a code release belies the purpose of the Debugging Mark to call attention to do something. Sometimes “doing something” means leaving the code as-is and putting in an appropriate, more permanent comment. This is better than leaving Debugging Marks to build-up over time. Very old Debugging Marks (left over from previous releases) are messy and can create confusion.
You should use a Debugging Mark.