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:

/// <summary>
/// Check the FormatException should be thrown when a give country data line contains a invalid number.
/// </summary>
[TestMethod]
public void FormatException_Should_Thrown_When_Parse_CountryLine_Containing_InvalidNumber()
{
  ...
}

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

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.

Answer 3

If you think that it's the best use of your time, do it, otherwise don't. I wouldnt.

Answer 4

For the example above, I would say that it's not necessary, unless you use a tool that extracts documentation from source (like javadoc or something).

A common rule of thumb is that the code says what you're doing and the comment says why, but since the name is so very verbose (which I think is ok, since no one ever has to type it) I don't think that the comment contributes anything.

Answer 5

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 6

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 7

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 8

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.