Should I document my unit test methods?

As it happens with private methods, unit test methods documentation can only be seen by who has access to the source code. Is it worth the effort spent on it?

By documentation I mean something开发者_开发知识库 like (but more descriptive):

/// <summary>
///A test for SomeClass.SomeMethod
///</summary>
[TestMethod()]
public void SomeMethodTest()
{
}

---

Unit tests should aim to be self descriptive, but there will always be cases where this goal cannot be achieved and thus description of what has been written is due.

In other words, try to make your unit tests so they don't need documentation, but if they need it, write it!

---

I would rather be inclined to saying that you should name your test method in a manner that is expressive with regards to what it tests: SomeMethodWillBehaveThisWayWhenCalledWithTheseParameters() although some people may find that controversial.

---

Oh yes!

Even if "who has access to the source code" is never ever going to be anyone else than you, it wont be the same you that look at it in a year (or even a month from now), trust me on that one :-)

---

You should document all code.

For unit tests, I usually say what I'm testing, and how it's tested. Putting "Test for Class.someMethod" is not very helpful.

---

I think it is good to document unit tests, my main reason for it being that you can explain why specific functionality is tested. My unit tests tend to end up with all sorts of weird extreme or unexpected parameters.

If a test fails a future programmer (or you with a bad memory) knows why a functionality was tested/implemented.

---

Yes. The reason I think that documenting unit tests is a good idea is that during development if you modify not just the API of your production classes but some internal behavior that causes some tests to fail, then it saves quite a bit of time to navigate to the test code, read the unit test documentation and ascertain whether or not you would have expected the test to fail given your recent behavior change or maybe something more subtle is occurring.

Without this documentation you would have to figure out what the test does from its name and the comments/code within the test.

Note that if you're simply going to just rewrite the name of the unit test in the documentation, then this is not very useful and I'd stick with just giving the unit test a descriptive name (i.e. the documentation should be more verbose than the unit test's name)

---

Yes. Tests may seem to be self-documenting, but the convolutions you have to go through sometimes to generate meaningful test data means that everything may not be immediately obvious to the eventual maintainer, who might just be YOU! Make your life easier - document your code.

---

A unit test should be simple enough and verbose enough to make it easy to understand. If you need to comment your unit test, maybe you should change its name, or maybe you should refactor it into smaller methods.

Refactoring test is a good practice, you HAVE to refactor your tests in fact, or they will become impossible to maintain.

Comments as I see them are almost always a sign that you should refactor that piece of code that you need to comment. What applies to production code applies to test code.

---

Most unit tests shouldn't need documentation. The name should make it clear which method they test and give an indication of the expected results. The code should be simple and clear. Unit tests shouldn't implement business rules, so documenting the "why" is usually unnecessary.

In the rare case that a test must be complex enough to warrant comments, they should be documented like any other code.

---

For MSTest (IDK if NUnit has something similar) it's useful a DescriptionAttribute for each test method, since they show up on the Test Results Panel on Visual Studio. More readable than the naming convention WhenThisHappenShouldHappenThis.

---

I find the message printed out by the unit test when it runs to be generally sufficient. For example, in Perl:

is(compare_bitstrings($bs1, $bs2, $gen), 1, 'compare_bitstrings - bs1 > bs2');

Gives

ok 74 - compare_bitstrings - bs1 > bs2

when run successfully. That tells me what I'm trying to do, and what the answer should be.

---

Absolutely!! Your unit tests should be documented every bit as well as your actual code. If for no other reason than the not uncommon circumstance of not knowing if it is your code or your test that has the bug.

---

When I write tests, I favor a comment for the test, followed with a descriptive test method name (such as S/S/R format mentioned in another answer's comments) because it is a habit my fellow developers and I got into when we started with CPPUNIT with C++. As I dabble in C#, the point mentioned by Lucas in his answer is a good one -- when the framework allows for it, the description field that can be used in the source code AND results is very handy, and I would favor a comment format that is usable in many places such as that.

All that being said, I think you need to look at how you or your development team typically handles code comments. Are folks in the general swing where they update comments when code is fixed, refactored ? Is the project smaller and will it always have the same few developers on it that work closely together ?

The projects I work on are larger scale, and depending on the state, it may be maintained by a team close together, a remote team, or co-developed or completely handed over to a vendor. In my scenarios, we attempt to spend the time to document and maintain the documentation in production and test code for those who will come along in the future.

If comments are usually an after-thought though, as much as it might pain me, if there is a chance your comments are going to fall out-of-date with the actual code/tests, it may not make sense to attempt to change the status quo.

---

I believe that "If the comment useless, better remove it". The documentation is used mostly for programmer who want to call your method, in this case "Who will call your test?". Let's take a look at this example?

/// <summary>
/// Test MapRadioNameFromWave when input 104 should return "VOV English"
/// </summary>
public void Test_MapRadioNameFromWave_Input_104_ShouldReturnVOVEnglish() {
    // Test
}

But if a test really need a comment, surely it's necessary!