[EMAIL PROTECTED] wrote: > >>From "The Design of Everyday Things", docs are a sign of poor design. > Even a single word, such as the word "Push" on the face of a door, is > an indication that the design can be improved. Please, rethink the > design instead of trying to compensate with more documentation.
This quote, with a naive reading, would seem to imply that "needing documentation is evidence of bad design." I think we can all agree that this interpretation is ludicrous: the only programming language, for example, which does not need documentation is the natural language, and that contains so many ambiguities that humans often get instructions wrong. If nothing else, documentation is necessary to explain "why X instead of Y," when both X and Y are perfectly valid, but mutually exclusive choices (CamelCase versus underscore_names). IMO, the correct interpretation of this reduces exactly to the principle of least surprise. If a door needs to have a sign that says "push," it means that a fair number of people have looked at the door and thought it was a pull-door. But they expect it to be a pull-door based on /experience with other doors,/ not some odd Platonic ideal of door-osity. Some surprise, however, (especially in Python) is necessary because the same feature can be seen more than one way: see the ever-present discussion about func(arg=default) scoping of default arguments. While "that's the way it is" shouldn't cover up true design flaws, arbitrary replacement with another behaviour doesn't work either: the other way will, ultimately, need the same order of documentation to catch surprises coming from the other way. -- http://mail.python.org/mailman/listinfo/python-list
