C# Question
September 26, 2004 7:52 PM   Subscribe

A C# question: I'm starting a new project at work, and we're going to be fully commenting each class/method/whatever, as well as write extensive unit tests (using NUnit). I very much like how the compiler generates warnings for uncommented methods, but it also warns me about my uncommented unit tests. Is there a way to disable these warnings for my unit tests?

All of the unit tests are going to go under a single namespace/directory called "Tests".

I've thought of a few different ways to get around this, but none is completely satisfactory:

1. I could add a #pragma line at the top of every unit test file to disable these specific warnings. That's not very elegant.

2. I could make my unit test classes internal. This makes sense to me since the unit tests shouldn't really be exposed in the API, but (a) NUnit doesn't see internal classes, and (b) everything I read says to make the classes public. I gave a cursory glance at the NUnit source code but couldn't figure out how to get it to see internal classes.

Any ideas? XML comments and unit testing are great practices, and I'm surprised I couldn't find anybody else online who'd had this problem.

Thanks!
posted by Khalad to Computers & Internet (10 answers total)
 
Why would you not comment unit tests?
posted by mischief at 8:11 PM on September 26, 2004


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.)
posted by Khalad at 8:33 PM on September 26, 2004


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?
posted by pascal at 8:54 PM on September 26, 2004


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.
posted by hattifattener at 10:39 PM on September 26, 2004


"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.
posted by mischief at 6:58 AM on September 27, 2004


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)?
posted by andrew cooke at 7:47 AM on September 27, 2004


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.
posted by majick at 10:00 AM on September 27, 2004


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.
posted by Khalad at 10:19 AM on September 27, 2004


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.
posted by majick at 11:53 AM on September 27, 2004


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!
posted by Khalad at 3:36 AM on September 29, 2004


« Older In Moveable Type 3.01D, to delete all content but...   |   IE and Print Stylesheets Newer »
This thread is closed to new comments.