Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

We wasted a lot of time on our last integration test on a bug that I think should have been found in unit testing. The problem was that an interface / service we called behaved different than we expected and the unit test didn't find this problem because we mocked that interface for the unit test and our mock was of course based on our mistaken interpretation of what the interface would do. Now I could be a bit angry at our dear coworker who provided the interface, because their description / specification of it (a terse JavaDoc comment) was ambiguous and contributed to our misunderstanding. On the other hand, I thought that the problem could have been avoided if those same coworkers had provided a mock implementation of their interface which we could call in our unit testing. Then the bug would have shown up much earlier and a lot of cursing could have been avoided.

Now, what's the best practice in organizing the creation of mock objects among teams who provide and use shared interfaces? What are your experiences?

share|improve this question
    
I hope in all this investigation of blame you included some for yourself for not asking the author if you understanding was correct... One question on your part could have saved all the pain. –  Walter Apr 3 '11 at 13:21
1  
Walter, thanks for your edits and constructive comment. Your suggestion does not answer the question directly, but is in fact a solution to the original problem I have. Since I find it so hard to ask good questions about one's own understanding, I came up with another idea: we could have asked the other team to review our plan to use their interface and they might have spotted the problem. –  Robert Jack Will Apr 4 '11 at 14:59
add comment

2 Answers

Ideally, yes.

Anyone who writes code that other people use is not bound to provide anything complementing the code. However, if you want people to use your code (and everyone should always be writing with this mentality), extensive relevant documentation - which may include examples - are extremely useful.

I don't think I've ever read documentation and have thought, "This is stupid; there's way too much documentation." People are naturally gifted at skipping over what they deem unnecessary. We, however, cannot simply mind-read and interpolate the documentation or concepts that have not been explained. So, it's safe to assume: there's no such thing as too much good documentation. It should also assume that the person reading it as a naive infant (i.e. make it as simple as possible).

Examples on how to instantiate and use a class is always helpful. Although, if the code relies too heavily on the documentation to be understood, that is another (separate) issue.

This answer shouldn't be seen as firepower that will justify yelling at your co-worker. It is merely a guideline of what I think is beneficial and should be done. While this is completely useless in your situation (although, I feel your question is basically a rant), the next best thing you can do is lead by example and hope your colleague comes around.

share|improve this answer
    
While I have found myself complaining about too much documentation, those instances have been rare (and was taking issue more with the quality that resulted in very long worded and confusing docs). –  Tim Post Apr 3 '11 at 11:18
    
@Tim: Thanks, have just edited - I was referring to good documentation. Unfortunately, anyone can write a bunch of rubbish as 'documentation'! –  Jonathan Khoo Apr 3 '11 at 11:23
add comment

Should the provider of an interface also provide a mock implementation for testing?

No, but the provider should also provide the sourcecode for their unittests. Reading these unittests you will get a good impression how the library should be used. Maybe you can add unittests to the provider-tests in order to specify what you expect from the provider.

There are many mocking tools/framework out there that can implement a fake/stub/mock.

Asking the provider for a mock implementation has no good cost/benefit relation because he cannot know which part of the fake implementation must be nearly identical to the real implementation and which part is just facade.

An other way around this is if the provider uses codecontracts to make sure that the lib is used in the specified way.

share|improve this answer
    
+1 "There are many Mocking tools/framework out there that can implement a fake/stub/mock." –  Alison Apr 3 '11 at 12:26
    
Unit Tests: I see two problems in using them as documentation: 1. they only show examples of what the service supports, but won't tell me if a certain use I have in mind is supported. 2. Reading unit tests is just about as demanding / tiring as reading code and I am looking for a solution that saves everybody work. I am looking for something that works automatically, like tests or contracts (which we're also looking into). –  Robert Jack Will Apr 4 '11 at 15:17
    
"Provider cannot know the use of the mock": I am not sure about that. For one thing the mock should check all the preconditions (is the service used right) and it should return some dummy values. Basically all that is needed to unit test a client. Could you elaborate more on what information the provider is missing to do this well? –  Robert Jack Will Apr 4 '11 at 15:21
    
the mock should check all the preconditions: why does the mock need to check if the real lib does this checking. If you have an integration tests with the real lib these tests should lead you to the problem. –  k3b Apr 4 '11 at 15:40
    
k3b: we want to find bugs as early as possible and integration test can be much later. This was exactly the problem that we had. Well, we're already working to improve the process so that integration tests can happen earlier and more often, but still unit tests should find as many bugs as possible. –  Robert Jack Will Apr 4 '11 at 15:46
show 1 more comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.