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;
}
[Update]
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
}
