What level of detail to use in an interface members descriptions?
        Posted  
        
            by 
                famousgarkin
            
        on Programmers
        
        See other posts from Programmers
        
            or by famousgarkin
        
        
        
        Published on 2012-08-30T10:14:27Z
        Indexed on 
            2012/08/30
            15:49 UTC
        
        
        Read the original article
        Hit count: 326
        
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.
© Programmers or respective owner