Ruff! principles: Don't burden the reader

Unless the merged interface, including inherited methods, mix-ins, and forwards, are clearly documented and linked, documentation related to classes and similar is even more of a headache for the reader than the programmer.

Consider the following code:

class create InputChannel {
    method read {args} {...}
    method close {} {...}
}
class create OutputChannel {
    method write {args} {...}
    method flush {args} {...}
    method close {} {...}
}
class create IOChannel {
    superclass InputChannel OutputChannel
    method close {} {...}
    method shutdown {direction} {...}
}

One might debate whether the above is good design. What is not debatable is that the documentation for IOChannel should

• cover all callable methods for the class, including inherited ones;
• include class relationships;
• reference the correct method when multiple classes in the inheritance tree implement the same method;
• not require the programmer to manually maintain this documentation as class interfaces and relationships get modified; and above all,
• not require the reader to manually walk the class relationships collecting or hunting for methods.

Which leads to

Ruff! principle – don’t burden the reader

Ruff! should not ask the reader to work out information that it can provide itself. This dovetails into the principle of non-repetition but targets the reader as well as the programmer.