How to be Explicit

• Guideline: Describe object semantics as explicitly as possible.
• Well-designed (minimal, complete) interface
• Good method names
• Up-to-date comments, especially Javadoc comments
• Easy to read code (but this is implementation, not interface)
• Design by Contract: pre-conditions, post-conditions, invariants
• Test suites: express your understanding of the semantics in a different way.
• Design objects that communicate to programmers how to properly use them. (good names, unsurprising semantics, etc.)

Why Be Explicit?

• Design by Contract and test suites help with "semantic discovery" and robustness.
• Its a contract, so both sides need to have a consistent understanding.
• If not, clients may make bad assumptions.
• Later, when implementation changes, can break client code.
• Being explicit and complete -- communicating effectively -- is an important first step in preventing semantic misunderstandings between designers and clients.

JTree's setModel, does it make a copy of the TreeModel object passed in? (Kind of a strategy?), or use the one as is. Javadoc didn't say. A friend of mine was complaining about having to step into the swing code to figure out the semantics, realizing full well that he wasn't really figuring out the fence, just the point within the fence. The semantic contract is a fenced in space, the full range of possible behavior a method can have when you invoke it. Any particular implementation is a cow grazing at one single point within that fence.

Student didn't know whether AbstractTableModel was used as is or cloned. To avoid this kind of confusion, I specified that the array passed to Matrix(int[][]) constructor is not used, and in the constructor I clone it. From a performance perspective, this seems like the wrong choice, because why always clone when it would be more efficient for clients to decide whether to clone before passing the array before they invoke the constructor. But then the Matrix would not have control of its state (a client could hold on to the reference and then change it), which means that Matrix couldn't promise to fulfill its contract.