This is another of Steve McConnell’s (author of Code Complete) gems.
Do we do this?
If not, why not?
Anytime you find yourself looking at a class’s implementation to figure out how to use the class, you’re not programming to the interface; you’re programming through the interface to the implementation. If you’re programming through the interface, encapsulation is broken, and once encapsulation starts to break down, abstraction won’t be far behind.
If you can’t figure out how to use a class based solely on its interface documentation, the right response is not to pull up the source code and look at the implementation. That’s good initiative but bad judgment. The right response is to contact the author of the class and say “I can’t figure out how to use this class.” The right response on the class-author’s part is not to answer your question face to face. the right response for the class author is to check out the class-interface file, modify the class-interface documentation, check the file back in, and then say “See if you can understand how it works now. “You want this dialog to occur in the interface code itself so that it will be preserved for future programmers. You don’t want the dialog to occur solely in your own mind, which will bake subtle semantic dependencies into the client code that uses the class. and you don’t want the dialog to occur interpersonally so that it benefits only your code but no one else’s.
Binarymist 