I am currently working on a project that has very little documentation overall. The team is working to change that. I am doing my part, by adding xml comments to the methods I make and the ones I edit, so that the automatic documentation generation tools can use them.
For some methods, complexity is either obvious or irrelevant.
But for some other methods, the way the code is built right now, they can seem like they are pretty light, but actually be very slow (talking about n³ and above here).
Of course, I am aware that there is an underlying problem and that refactoring is probably needed. But we neither have the time nor the budget to refactor everything within a reasonable delay, so in the meanwhile, I would like to communicate this information as a warning.
example:
/// <summary>
/// Tests if a thing is in a valid state. WARNING: This runs in O(n³)
/// </summary>
/// <returns>The validity of the thing</returns>
public virtual bool IsSomethingValid()
{
return DoCodeThatIsMoreComplexThanItLooks();
}
I usually find those cases when doing some performance improvements, but at this point, this happens pretty often, and I think adding such big warnings too often will lose its impact.
So my idea would be to simply add it to the standard XML comment format, and put the complexity regardless of what it is, as a bit of information that may be useful or interesting.
Is there a standard way to communicate the complexity of a method in XML comments? like a tag that Visual Studio will understand (but doesn't add by default).
n
here?". If you do go down that route, you should define it. That might end up as "This runs in O(k * n * m), where k ~ Foo.Count, n ~ Bar.Count, m ~ Baz.Count"