Quick Tip: Code Comment Breadcrumbs

Overly long code comments can decrease the readability of your code.  

If your code requires a lengthy explanation, by all means, include enough of a comment to help the next person understand what is going on.  (Though, generally speaking, that is a code smell that indicates you may need to simplify your logic.)

However, oftentimes the code is easily understandable, but there may have been obvious alternatives that you chose to forego for whatever reason.  In those situations, I try to provide a full write-up of my decision-making process in my bug database.  I use FogBugz, but the concept applies to other bug tracking databases, such as GitHub.

Within my code, I'll include a one-line summary of my thought process and leave a breadcrumb to the full discussion using a short abbreviation for my bug database and the relevant case or issue number.

For example:

'used a dictionary instead of collection to detect duplicates (see FB 3251)

'used snapshot recordset to deal with record locking issue (see GH 27)

This is a great way to boost the signal-to-noise ratio of your code without sacrificing valuable context.