To comment or not to comment

Damn, Chad Myer‘s post about mistakes of comment usage in code made me think !

I tend to agree with him about the fact that your own code should be self explanatory, so that code comment is redundant.
But on the other hand, sometimes a little comment about the flow of the code always tends to help me understand the code itself better.
That aside, my code doesn’t have that much of code comment ( except for the //TODO: lines ) !
So I had to search a bit, but found a good example IMO, to show of the need of code comment… This to answer Chad’s question !

So here it is, what do you think ? Is the comment valid, should it stay in the code ? I think it should ! It still seems very obvious, but I would like to keep it in.

/// The general list has 2 internal lists:
/// * one pointing to the actual objects in the database
/// * one pointing to the actual objects in memory
/// To get the total count we have to take following flow into account
/// * the memory reference can be different from the database reference, so we combine the 2 counts and subtract the objects that are already available in the database list
public int Count
int totalCount = 0;

totalCount = ReferenceEquals(this.internalListMemory, null) ? 0 : this.internalListMemory.Count;
totalCount += ReferenceEquals(this.internalListDatabase, null) ? 0 : this.internalListDatabase.listCount;
foreach (DictionaryEntry internalListDataObjectsElement in this.internalListMemory)
if (!ReferenceEquals(this.internalListDatabase, null) && this.internalListDatabase.ListFind(internalListDataObjectsElement.Key))
totalCount -= 1;

return totalCount;

Like I stated above, maybe the code comment is a bit to abvious ( so it could be omitted, but I’m in favour to let it in ).
So here maybe another example… but also here a small suggestion, this could maybe be changed to a //TODO: version. Depending on the work flow of programmer and his Task list.

/// There is a bug with the Excel interop for Office XP ! We first need to set the current culture to en-US to get correct date time values
public void StartTimeProcessing()
System.Threading.Thread.CurrentThread.CurrentCulture = System.Globalization.CultureInfo.CreateSpecificCulture("en-US");

- Rest of code with use of the interop code

2 thoughts on “To comment or not to comment”

  1. Sometimes the code is just ugly and you have no choice but to put a comment. Your 2nd example (Interop) is an example of this. Sometimes you just have to hack in order to get around a bug in another system, or a poorly designed API (COM), etc. In these cases, what choice do we have but to comment?

    In your first example, though, the comment is useful, but brittle. I could see how the counting code might easily change in the future or new facts may present themselves later.

    Perhaps you could, instead, add a function to one of the lists called something like DistinctUnion() which returns a list of the union’d contents of the lists (with the duplicates removed. Your function would then be as simple as:

    return internalListMemory.DistinctUnion(internalListDatabase).Count;

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.