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.

I am extracting interfaces from some classes in .NET, and I am not completely sure about what level of detail of description to use for some of the interface members (properties, methods).

An example:

interface ISomeInterface
{
    /// <summary>
    /// Checks if the object is checked out.
    /// </summary>
    /// <returns>
    /// Returns true if the object is checked out, or if the object locking is not enabled,
    /// otherwise returns false.
    /// </returns>
    bool IsObjectCheckedOut();
}

class SomeImplementation : ISomeInterface
{
    public bool IsObjectCheckedOut()
    {
        // An implementation of the method that returns true if the object is checked out,
        // or if the object locking is not enabled
    }
}

The part in question is the <returns>...</returns> section of the IsObjectCheckedOut description in the interface.

Is it ok to include such a detail about return value in the interface itself, as the code that will work with the interface should know exactly what that method will do? All the current implementations of the method will do just that. But is it ok to limit the possible other/future implementations by description this way?

Or should this not be included in the interface description, as there is no way to actually ensure that other/future implementations will do exactly this? Is it better to be as general as possible regarding the interface in such circumstances?

I am currently inclined to the latter option.

share|improve this question
add comment

3 Answers

up vote 6 down vote accepted

I would advise taking a step back and looking at what you're trying to achieve.

What does the XML documentation give you? XDoc Documentation? Think about what you want to see in that document. Intellisense? Think about what you want to see when someone is using that method from the interface. Or are you just doing it because you think you should? If so then stop it, you're wasting valuable time.

Already I can see that the method name doesn't match what the method does. And that's probably the reason you're having to ask this question.

Should the method really be named IsObjectCheckedOutOrNonLockable()? Or does IsObjectNonLockable() implicitly include "checked out" on the objects you currently have implemented? Or is there a better description that covers all those conditions?

Does renaming the method make it more obvious what you should put in the XML documentation and more obvious what is expected of future implementations?

share|improve this answer
1  
+1. Actually, after changing the function name the documentation may probably become obsolet. –  Doc Brown Aug 30 '12 at 12:16
    
Though all of the answers are very helpful, I'm marking this one as the One. I think this is really the biggest problem of all with the code at hand. I took a step back, went through the API again, and you are correct sir. Most of the classes and methods are non-atomic operations, too ambiguous about what they actually do, and really not suitable for extracting to the interface directly. Now I just need to come up with a good solution how to go about this and convince others in the team :) Thanks! –  famousgarkin Oct 16 '12 at 14:59
add comment

An interface defines an API and a protocol. I.e., two interfaces can have the same API, but have different protocols. Method A in Interface 1 can do one thing and method A in interface 2 can do a completely different thing.

An interface should only enforce an API (by the compiler) and a protocol (by the developer); it shouldn't enforce or even hint at any implementation details.

Your problem lies in the approach of "extracting the interface" from a concrete class. You (and your code) already know (and possibly care) about the actual implementation.

Instead of doing that, try refactoring client code to use a hypothetical interface that looks right and its goal is self-explanatory by its use. Then, and only then, adjust your concrete class to implement that interface.

share|improve this answer
add comment

Be as specific as you can describing how interfaces should look and behave. There is no use having an interface method whose return value is ambiguous - it breaks the whole notion of interfaces. Just because few languages offer the ability to enforce all the requirements and intentions of the interface, such as the precondition and postcondition support in Eiffel, it should not stop you communicating expectations to both callers and implementers.

share|improve this answer
add 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.