C# Question

Cause it's tedious and unnecessary? This is my first time unit testing, but that seems like major overkill. Aren't the tests themselves supposed to be the documentation? Seriously, why would you comment unit tests? (Excuse my flippant/defensive tone. I'm finding it difficult to excise it from this comment.)

Because when they fail, it might not be you that has to work out why. Seriously, I think it's a good idea to comment the unit tests - in an ideal world, the unit tests get run as part of your build process (by this, I mean the actual product build rather than a developer building on their own desktop) and unit test failures get treated as bugs. Your QA team's job will be that much easier if you document the assumptions under which the test operates, what it is that is being tested, how it is that your test actually does test that, and what might be wrong if it fails (obviously this last part is going to be a bit speculative.) If you are the only person who is ever going to run the tests, or don't have a QA department or a build process, then maybe you needn't bother - but if that's the case, why are you bothering to comment the code?

And in my experience, unit tests are sometimes as complicated as the code. Certainly they can involve many non-obvious decisions, all of which should (in an ideal world) be explained in the comments. Even if the unit test is just of the form "check that f(x) = y for this table of (x,y)", the test ought to be checking possible edge cases, special cases, etc., and ought to be performing a full coverage of the code it's testing; and the tests that do those things need to be documented as to why those particular values are being fed through. Often there will be some values of 'x' for which it is not immediately obvious what the correct value of 'y' is, and the tests need to explain the reasoning for choosing that value of 'y'. (Especially because that reasoning might be incorrect, or might rely on an assumption which later changes.) I'm not actually a huge fan of unit testing, but I am a huge fan of commenting code.

"Aren't the tests themselves supposed to be the documentation?" No, absolutely not! Test modules require documentation that is as detailed, if not more detailed, than the code. The code simply 'is'; the tests proves that the code works and as such, should be described thoroughly.

any chance of an answer to the question (i'm curious) (and i don't think it's 100% obvious that documentation is always necessary, but i'm not going to argue it here)?

I'd just bite the bullet and stick in a #pragma. You've chosen your development style -- to minimally comment tests -- and you'd like the compiler to respect that. This is, in fact, the purpose of compiler pragmas.

I've got nothing against #pragmas, but it would be a lot nicer if there were a way to apply the #pragma to the entire Tests directory in one fell swoop rather than add a line to each test file. My ideal solution is still to make the test classes internal. Is that feasible at all? Is it possible to modify NUnit to check my assembly's internal classes, too, or is that not even possible with .NET reflection? Thanks for the help anyways, everyone! I might just comment the damn tests, if it's not too huge a bother.

I don't know enough about .NET (in fact, very little) to authoritatively answer your question about the ideal, but I suspect that you aren't going to be able to get your test harness to violate encapsulation to reach internal test classes. Certainly if I were defining a language, I'd want "visible to a test harness outside the namespace" and "a class internal to the namespace" at odds with each other.

For what it's worth, I've figured out how to resolve this problem. The solution is to compile the test suite separately from the main source, so I only have to specify the /doc option for the main source files. I don't think this can be done with Visual Studio. Visual Studio always creates an assembly from each project, and compiles an entire project at once. I need my tests to tests the internal classes of the project, so splitting the tests into a separate project wouldn't work since that would create two separate assemblies, meaning the tests could only see the public members of the main assembly. So, I'll be switching to NAnt to be able to have more control over the build process. The C# compiler has a /target:module option that is inaccessible from Visual Studio. Using that should let me build the main source files and the test suite as separate modules, and then combine the modules into a single assembly. I may or may not still comment the unit tests, but at least now that'll be my choice. This seems like the "right" way to solve the problem. Oh, and as it turns out #pragma doesn't even exist in C#. So much for that option!