Rob Smyth

Thursday, 19 August 2010

Code Smell Metric - Doco Fluff Metric (DFM)

Code documentation is one of those things that is so easy to do to without adding anything useful. The problem is that the added lines of code/text appear have no value and reduce code readability. A case of less is more. Documentation can be useful, but nonsense documentation is worse than no documentation at all.

So a metric that detects nonsense documentation ("fluff"?) is another little helper.

Here is a real world example:

/// <summary>
/// Thread Name.
/// </summary>
public string ThreadName;
/// <summary>
/// Time Stamp.
/// </summary>
public DateTime TimeStamp;


A trival example but I recon it is less readable than:

public string ThreadName;
public DateTime TimeStamp;


So the metric is: If the documentation, with white spaces removed, case insensitive matches the property, method, or type then flag as doco fluff.

1 comment:

Nigel said...

You could set your syntax highlighting to make comments almost invisible... then you wouldn't be confused by them ;)

Nigel