Joe Enos

The absolute worst thing in the world, the one and only thing that drives me nuts – over-commented code.

People, please, write comments to describe why you are doing something, or what business purpose it satisfies, or things to watch out for when you’re calling the code. Or tell me the units involved if you accept an ambiguously named parameter (Microsoft is guilty of not doing this).

Don’t write a comment around every single line of code, telling me you are incrementing a variable, or looping through a collection, or a dozen other painfully obvious things you are doing. And don’t comment your “AddForm()” method with “//Come here to add a form”. Those comments are just stupid and distract from what we should be looking at. Make your code self-documenting, and put actual useful comments in, or none at all.

If everyone would just do these simple things, the world would be a wonderful place to live.

Document the units

Microsoft does this all the time, and it drives me nuts. If you have a number that represents a time span, or some other measurement, tell me the units. I’ve had to go to MSDN several times to figure out if “timeout”, or a similar parameter, means seconds, minutes, milliseconds, etc. You can include the units in the parameter name itself, or use XML-doc comments to define it. Either way is fine.

public void SetTimeoutPeriod(int timeoutSeconds) { }

/// <summary>
/// Sets the timeout period.
/// </summary>
/// <param name="timeout">The time to expiration, in seconds.</param>
public void SetTimeoutPeriod(int timeout) { }

Don’t tell me every little thing you’re doing

Everyone who’s looking at your code can read basic loops, assignments, and other simple language constructs. Don’t tell me every little thing you’re doing – if you’re doing something weird, then maybe it’s ok, but keep that to a minimum.

// loops through the records
foreach (var record in records)
{
  // get the title and upper-case it
  string title = record.Title.ToUpper();

  // write the title to the page
  lblTitle.Text = title;
}

Useless definition comments

I’ve been in places with the rule of “you must XML-comment everything”. However, if your code is self-documenting with good names, many methods and properties don’t need documentation. When you force developers to put in comments, you’ll get useless garbage just for the sake of putting something in.

/// <summary>
/// Gets the median score of a group of scores.
/// </summary>
/// <param name="scores">The scores to get the median of.</param>
public int GetMedianScore(int[] scores)
{
  // implementation
}

Self-documenting code means your methods and variables are named appropriately, so that you can understand what’s happening just by reading the code. Comments, when they are there, should be useful and add to the story, rather than being there for the sake of having comments.