Documenting Interfaces [DI12] [WHAT]
Tip DI12
Many object-oriented programming languages support the notion of interfaces - or what are effectively pure abstract classes with no implementation. Such interfaces provide a way for code to work with objects of many different types, as long as they conform to the interface, without the additional complexity than comes with traditional inheritance. There are some specific considerations to keep in mind with interfaces.
When defining such interfaces, ensure they are fully documented so that:
Users of the interface will know how to use it, regardless of derived object types.
Programmers creating concrete classes that implement the interface know how to properly implement it.
That means every method, property, etc. of the interface should be documented, as shown in the following example:
