The selfish class

classes and frameworks should be bundled with at least one fully functional set of working, concrete subclasses or components (in other words, a working example). Such example objects, classes, and frameworks should come with fully functional, working test programs, and these programs should be accompanied by sample input and output objects or files, where relevant. It’s almost always not enough to merely document an artifact’s interface. Providing working examples of how interfaces are actually used helps to resolve ambiguity and uncertainty and fosters confidence. Instructions that describe how run these examples should be included too. These minimal working examples are particularly important when the user is called upon to master complex interfaces. Users should not be left sitting frustrated on Christmas Day because the batteries were not included. One way to learn how a new artifact works is to methodically study its code and documentation. Another is to dive in cold and experiment with the artifact, and thereby get a sense of what it can do. Initial success with such experiments will give programmers the confidence they need to delve more deeply into these object. Working examples can serve as test beds for exploratory experimentation. Such exploration can permit programmers to incrementally learn how to use an artifact, while keeping the growing example working. Programmers can progress from tinkering with this working examples to verify that they can rebuild them correctly, to a point where they feel that their command of the interface of the objects they are using is sufficient to justify embedding these objects in their own applications. At the beginning of this process, when every aspect of such a program will be new, and probably opaque to the programmer, it is particularly important that getting the artifact to work be as painless as possible. Programs should exhibit reasonable behavior in the absence of arguments or pre-existing data. Therefore, design objects so that they will exhibit reasonable behavior with default arguments. Provide everything a programmer needs to try out these objects. Make it as easy as possible for designers to see a working example. The Selfish Class Page 8 of 19 http://www.laputan.org/selfish/selfish.html 8/27/01 Designers should strive to ensure that a user's first encounter with their creations does not require elaborate preparation. You should strive to make installation effortless, and minimize user configurations. A user will never be so ignorant of the ramifications of configuration decisions as upon the first time he or she confronts a new application. Hence, programs delivered in source form should build in response to make, or something like it. Installation programs should provide a default configuration button, and allow customization later on. A design, and the objects that embody it, survive and evolve only if they are used. To be reused, they must attract programmers. To do this, they must make a good first impression. Like peacock feathers, an initial, painless presentation of impressive functionality can enhance an object's appeal. Objects which do this can flourish, and those which cannot, even if they are technically superior in other ways, may not. The following box gives several examples of things that don’t work out-of-the-box, and of things that do: