Posted on Jun 09, 2015

I write a lot of code comments. It helps me structure my code and make it a bit easier to scan, but it helps my future self too: understand why I did something; alerts for pitfalls or not so obvious code structures; etc.  I've also written apologies to other developers who may come across my code one day. :P

Something that I've started doing in the past year is "tagging" my code: adding hashtags to act as bookmarks to help me find key lines of code that are related to something I'm working on or something I did in the past.

Some examples:

// #tags #kludge #revisit

...or...

// #tags #2015rebuild #govLimits

They always start with "#tags" so I can find all the tags later (doing a search inside project files) and remind myself of what keywords I used, and then follow up with something more descriptive about whatever I'm tagging.

When I first started using this technique I was doing a code audit, looking for areas that had the potential to break Salesforce govenor limits if the database got to a certain size.  Being able to tag the code blocks as break points and the particular govenor limit the code was going to transgress made it really easy later on for another developer to find the code that I highlighted and see my code comments about how to potentially solve the problem.

I'm pretty sure there are add ons for your text editor of choice to drop in bookmarks through out your code, but I've often found that they're just bookmarks, with no option to provide contextual information about why the bookmark exists, the UI and method for adding bookmarks was usually kinda clunky (certainly not as fast as just typing in your code), the bookmarks were often maintained separately from the code itself so they couldn't be shared with other developers and they might not have your text editor or add ons installed. This seemed to me like a light weight solution that is easily understood by other people coming to your code, regardless of their toolset.

There's probably a syntax for this that ties better into auto-documentation generating tools which I'm unaware of.  Enlighten me in the comments!

Categories: 

Add new comment

Filtered HTML

  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Lines and paragraphs break automatically.

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.
By submitting this form, you accept the Mollom privacy policy.