Is summary necessary in unit test method

Question

Since the naming of a unit test method makes its purpose more meaningful, is it necessary to add a summary to a unit test method?

Example:

/// 

        

Answer 1

Not necessary, but if you feel the XML comments add value above and beyond the name of the unit test itself (which looks like to be comprehensive) then you'll be doing other developers a service.

If the summary is essentially a direct duplicate of the unit test method name, then I think this is overkill.

Answer 2

It is necessary to add a summary when the summary can provide more information that can/should be encoded in method name. Please note that when I say "necessary" when referring to any documentation, I mean is "necessary to convey 100% of needed context/detail/nuances to a new coder inheriting the project or to you yourself 5 years later".

Answer 3

I actually prefer to use the DescriptionAttribute over a summary tag. The reason being that the value of the Description attribute will show up in a results file. It makes failures easier to understand when you're just looking at a log file

[TestMethod,Description("Ensure feature X doesn't regress Y")]
public void TestFeatureX42() {
  ..
}

Answer 4

I think the long descriptive name is more important than the XML comment. Since the unit test isn't going to be part of an API, you don't need the XML comment.

For Example:

[TestMethod]
public void FormatException_Should_Thrown_When_Parse_CountryLine_Containing_InvalidNumber()
{
  ...
}

is more useful than:

///<summary>
/// Exception Should Thrown When Parse CountryLine Containing InvalidNumber
///</summary>
[TestMethod]
public void Test42()
{
  ...
}

XML Comments should be used for documenting APIs and frameworks.

Answer 5

An XML comment is totally unnecessary if you have a descriptive method name. And it's a must for unit-test methods.

You're already on the right track having a descriptive test method name. (Many agile and TDD practitioners believe that a test method should include "should", e.g. as shown in link text this blog post.

Personally, I like method names like this:

MyClass_OnInvalidInput_ShouldThrowFormatException()

But that's merely my personal preference.

Answer 6

Personally, I try to make the tests easy enough to read that documentation would be redundant. I use inline comments within the test method to explain why I'm doing something a particular way, not what I'm doing.