ANN: Dao Language v.0.9.6-beta is release!

[Christopher Subich]

JohnBMudd at gmail.com 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.