By extension that's something that often goes for documentation comments (Javadoc, doxygen, etc.). When reading those I find it not really useful to learn that the frobFoo(Foo f) method frobs a foo and leaving the use of that method, what frobbing is and what a Foo is out of that documentation. Figuring out how to use something larger is much easier when classes come accompanied by usage samples and some notes about how they fit into the larger picture.