http://commons.oreilly.com/wiki/index.php?title=Make_Interfaces_Easy_to_Use_Correctly_and_Hard_to_Use_Incorrectly&action=history&feed=atom 2013-05-23T18:39:34Z Revision history for this page on the wiki MediaWiki 1.11.0 http://commons.oreilly.com/wiki/index.php?title=Make_Interfaces_Easy_to_Use_Correctly_and_Hard_to_Use_Incorrectly&diff=24663&oldid=prev 2009-07-07T12:21:29Z

<p></p> <table style="background-color: white; color:black;"> <col class='diff-marker' /> <col class='diff-content' /> <col class='diff-marker' /> <col class='diff-content' /> <tr> <td colspan='2' style="background-color: white; color:black;">←Older revision</td> <td colspan='2' style="background-color: white; color:black;">Revision as of 12:21, 7 July 2009</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 12:</td> <td colspan="2" class="diff-lineno">Line 12:</td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Above all, remember that interfaces exist for the convenience of their users, not their implementers.</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Above all, remember that interfaces exist for the convenience of their users, not their implementers.</div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>By [[Scott Meyers]]</div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>This work is licensed under a [http://creativecommons.org/licenses/by/3.0/us/ Creative Commons Attribution 3] </div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Back to [[97 Things Every Programmer Should Know]] home page</div></td></tr> <!-- diff cache key wikicontent:diff:version:1.11a:oldid:21675:newid:24663 --> </table>

Kevlin http://commons.oreilly.com/wiki/index.php?title=Make_Interfaces_Easy_to_Use_Correctly_and_Hard_to_Use_Incorrectly&diff=21675&oldid=prev 2008-11-22T16:00:32Z

<p></p> <table style="background-color: white; color:black;"> <col class='diff-marker' /> <col class='diff-content' /> <col class='diff-marker' /> <col class='diff-content' /> <tr> <td colspan='2' style="background-color: white; color:black;">←Older revision</td> <td colspan='2' style="background-color: white; color:black;">Revision as of 16:00, 22 November 2008</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 1:</td> <td colspan="2" class="diff-lineno">Line 1:</td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>One of the most common tasks in software development is interface specification. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>Interfaces occur at the highest level of abstraction (user interfaces), at the lowest (function interfaces), and at levels in between (class interfaces, library interfaces, etc.). <del style="color: red; font-weight: bold; text-decoration: none;"> </del>Regardless of whether you work with end users to specify how they'll interact with a system, collaborate with developers to specify an API, or declare functions private to a class, interface design is an important part of your job. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>If you do it well, your interfaces will be a pleasure to use and will boost others' productivity. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>If you do it poorly, your interfaces will be a source of frustration and errors.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>One of the most common tasks in software development is interface specification. Interfaces occur at the highest level of abstraction (user interfaces), at the lowest (function interfaces), and at levels in between (class interfaces, library interfaces, etc.). Regardless of whether you work with end users to specify how they'll interact with a system, collaborate with developers to specify an API, or declare functions private to a class, interface design is an important part of your job. If you do it well, your interfaces will be a pleasure to use and will boost others' productivity. If you do it poorly, your interfaces will be a source of frustration and errors.</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Good interfaces are:</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Good interfaces are:</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>* '''Easy to use correctly.''' <del style="color: red; font-weight: bold; text-decoration: none;"> </del>People using a well-designed interface almost always use the interface correctly, because that's the path of least resistance. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>In a GUI, they almost always click on the right icon, button, or menu entry, because it's the obvious and easy thing to do. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>In an API, they almost always pass the correct parameters with the correct values, because that's what's most natural. With interfaces that are easy to use correctly, ''things just work.''</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>* '''Easy to use correctly.''' People using a well-designed interface almost always use the interface correctly, because that's the path of least resistance. In a GUI, they almost always click on the right icon, button, or menu entry, because it's the obvious and easy thing to do. In an API, they almost always pass the correct parameters with the correct values, because that's what's most natural. With interfaces that are easy to use correctly, ''things just work.''</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>* '''Hard to use incorrectly.''' <del style="color: red; font-weight: bold; text-decoration: none;"> </del>Good interfaces anticipate mistakes people might make and make them difficult <del style="color: red; font-weight: bold; text-decoration: none;">-- </del>ideally impossible <del style="color: red; font-weight: bold; text-decoration: none;">-- </del>to commit. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>A GUI might disable or remove commands that make no sense in the current context, for example, or an API might eliminate argument-ordering problems by allowing parameters to be passed in any order.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>* '''Hard to use incorrectly.''' Good interfaces anticipate mistakes people might make and make them difficult <ins style="color: red; font-weight: bold; text-decoration: none;">&amp;mdash; </ins>ideally impossible <ins style="color: red; font-weight: bold; text-decoration: none;">&amp;mdash; </ins>to commit. A GUI might disable or remove commands that make no sense in the current context, for example, or an API might eliminate argument-ordering problems by allowing parameters to be passed in any order.</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>A good way to design interfaces that are easy to use correctly is to exercise them before they exist. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>Mock up a GUI <del style="color: red; font-weight: bold; text-decoration: none;">-- </del>possibly on a whiteboard or using index cards on a table <del style="color: red; font-weight: bold; text-decoration: none;">-- </del>and play with it before any underlying code has been created. Write calls to an API before the functions have been declared. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>Walk through common use cases and specify how you ''want'' the interface to behave. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>What do you ''want'' to be able to click on? <del style="color: red; font-weight: bold; text-decoration: none;"> </del>What do you ''want'' to be able to pass? <del style="color: red; font-weight: bold; text-decoration: none;"> </del>Easy to use interfaces seem natural, because they let you do what you want to do. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>You're more likely to come up with such interfaces if you develop them from a user's point of view. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>(This perspective is one of the strengths of test-first programming.)</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>A good way to design interfaces that are easy to use correctly is to exercise them before they exist. Mock up a GUI <ins style="color: red; font-weight: bold; text-decoration: none;">&amp;mdash; </ins>possibly on a whiteboard or using index cards on a table <ins style="color: red; font-weight: bold; text-decoration: none;">&amp;mdash; </ins>and play with it before any underlying code has been created. Write calls to an API before the functions have been declared. Walk through common use cases and specify how you ''want'' the interface to behave. What do you ''want'' to be able to click on? What do you ''want'' to be able to pass? Easy to use interfaces seem natural, because they let you do what you want to do. You're more likely to come up with such interfaces if you develop them from a user's point of view. (This perspective is one of the strengths of test-first programming.)</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>Making interfaces hard to use incorrectly requires two things. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>First, you must anticipate errors users might make and find ways to prevent them. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>Second, you must observe how an interface is misused during early release and modify the interface <del style="color: red; font-weight: bold; text-decoration: none;">-- </del>yes, modify the interface! <del style="color: red; font-weight: bold; text-decoration: none;">-- </del>to prevent such errors. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>The best way to prevent incorrect use is to make such use impossible. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>If users keep wanting to undo an irrevocable action, try to make the action revocable. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>If they keep passing the wrong value to an API, do your best to modify the API to take the values that users want to pass.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Making interfaces hard to use incorrectly requires two things. First, you must anticipate errors users might make and find ways to prevent them. Second, you must observe how an interface is misused during early release and modify the interface <ins style="color: red; font-weight: bold; text-decoration: none;">&amp;mdash; </ins>yes, modify the interface! <ins style="color: red; font-weight: bold; text-decoration: none;">&amp;mdash; </ins>to prevent such errors. The best way to prevent incorrect use is to make such use impossible. If users keep wanting to undo an irrevocable action, try to make the action revocable. If they keep passing the wrong value to an API, do your best to modify the API to take the values that users want to pass.</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Above all, remember that interfaces exist for the convenience of their users, not their implementers.</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Above all, remember that interfaces exist for the convenience of their users, not their implementers.</div></td></tr> </table>

Kevlin http://commons.oreilly.com/wiki/index.php?title=Make_Interfaces_Easy_to_Use_Correctly_and_Hard_to_Use_Incorrectly&diff=12970&oldid=prev 2008-11-11T02:27:10Z

<p></p> <table style="background-color: white; color:black;"> <col class='diff-marker' /> <col class='diff-content' /> <col class='diff-marker' /> <col class='diff-content' /> <tr> <td colspan='2' style="background-color: white; color:black;">←Older revision</td> <td colspan='2' style="background-color: white; color:black;">Revision as of 02:27, 11 November 2008</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 1:</td> <td colspan="2" class="diff-lineno">Line 1:</td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>One of the most common tasks in software development is interface specification. Interfaces occur at the highest level of abstraction (user interfaces), at the lowest (function interfaces), and at levels in between (class interfaces, library interfaces, etc.). Regardless of whether you work with end users to specify how they'll interact with a system, collaborate with developers to specify an API, or declare functions private to a class, interface design is an important part of your job. If you do it well, your interfaces will be a pleasure to use and will <del style="color: red; font-weight: bold; text-decoration: none;">actually </del>boost productivity. If you do it poorly, your interfaces will be a source of frustration and errors.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>One of the most common tasks in software development is interface specification. Interfaces occur at the highest level of abstraction (user interfaces), at the lowest (function interfaces), and at levels in between (class interfaces, library interfaces, etc.). Regardless of whether you work with end users to specify how they'll interact with a system, collaborate with developers to specify an API, or declare functions private to a class, interface design is an important part of your job. If you do it well, your interfaces will be a pleasure to use and will boost <ins style="color: red; font-weight: bold; text-decoration: none;">others' </ins>productivity. If you do it poorly, your interfaces will be a source of frustration and errors.</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Good interfaces are:</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Good interfaces are:</div></td></tr> <tr><td colspan="2" class="diff-lineno">Line 7:</td> <td colspan="2" class="diff-lineno">Line 7:</td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>* '''Hard to use incorrectly.''' Good interfaces anticipate mistakes people might make and make them difficult -- ideally impossible -- to commit. A GUI might disable or remove commands that make no sense in the current context, for example, or an API might eliminate argument-ordering problems by allowing parameters to be passed in any order.</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>* '''Hard to use incorrectly.''' Good interfaces anticipate mistakes people might make and make them difficult -- ideally impossible -- to commit. A GUI might disable or remove commands that make no sense in the current context, for example, or an API might eliminate argument-ordering problems by allowing parameters to be passed in any order.</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>A good way to design interfaces that are easy to use correctly is to exercise them before they exist. Mock up a GUI -- possibly on a whiteboard or using index cards on a table -- and play with it before <del style="color: red; font-weight: bold; text-decoration: none;">the </del>underlying code has been created. Write calls to an API before the functions have been declared. Walk through common use cases and specify how you ''want'' the interface to behave. What do you ''want'' to be able to click on? What do you ''want'' to be able to pass? Easy to use interfaces seem natural, because they let you do what you want to do. You're more likely to come up with such interfaces if you develop them from a user's point of view. (This perspective is one of the strengths of test-first programming.)</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>A good way to design interfaces that are easy to use correctly is to exercise them before they exist. Mock up a GUI -- possibly on a whiteboard or using index cards on a table -- and play with it before <ins style="color: red; font-weight: bold; text-decoration: none;">any </ins>underlying code has been created. Write calls to an API before the functions have been declared. Walk through common use cases and specify how you ''want'' the interface to behave. What do you ''want'' to be able to click on? What do you ''want'' to be able to pass? Easy to use interfaces seem natural, because they let you do what you want to do. You're more likely to come up with such interfaces if you develop them from a user's point of view. (This perspective is one of the strengths of test-first programming.)</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Making interfaces hard to use incorrectly requires two things. First, you must anticipate errors users might make and find ways to prevent them. Second, you must observe how an interface is misused during early release and modify the interface -- yes, modify the interface! -- to prevent such errors. The best way to prevent incorrect use is to make such use impossible. If users keep wanting to undo an irrevocable action, try to make the action revocable. If they keep passing the wrong value to an API, do your best to modify the API to take the values that users want to pass.</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Making interfaces hard to use incorrectly requires two things. First, you must anticipate errors users might make and find ways to prevent them. Second, you must observe how an interface is misused during early release and modify the interface -- yes, modify the interface! -- to prevent such errors. The best way to prevent incorrect use is to make such use impossible. If users keep wanting to undo an irrevocable action, try to make the action revocable. If they keep passing the wrong value to an API, do your best to modify the API to take the values that users want to pass.</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Above all, remember that interfaces exist for the convenience of their users, not their implementers.</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Above all, remember that interfaces exist for the convenience of their users, not their implementers.</div></td></tr> </table>

ScottMeyers http://commons.oreilly.com/wiki/index.php?title=Make_Interfaces_Easy_to_Use_Correctly_and_Hard_to_Use_Incorrectly&diff=12969&oldid=prev 2008-11-11T02:20:55Z

<p></p> <table style="background-color: white; color:black;"> <col class='diff-marker' /> <col class='diff-content' /> <col class='diff-marker' /> <col class='diff-content' /> <tr> <td colspan='2' style="background-color: white; color:black;">←Older revision</td> <td colspan='2' style="background-color: white; color:black;">Revision as of 02:20, 11 November 2008</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 1:</td> <td colspan="2" class="diff-lineno">Line 1:</td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>One of the most common tasks in software development is interface specification. Interfaces occur at the highest level of abstraction (user interfaces), at the lowest (function interfaces), and at levels in between (class interfaces, library <del style="color: red; font-weight: bold; text-decoration: none;">interfaces, package </del>interfaces, etc.). Regardless of whether you work with end users to specify how they'll interact with a system <del style="color: red; font-weight: bold; text-decoration: none;">under design</del>, collaborate with <del style="color: red; font-weight: bold; text-decoration: none;">other </del>developers to specify an API, or declare functions private to a class <del style="color: red; font-weight: bold; text-decoration: none;">you're working on</del>, interface design is an important part of your job. If you do it well, your interfaces will be a pleasure to use and will actually boost productivity. If you do it poorly, your interfaces will be a source of frustration and errors.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>One of the most common tasks in software development is interface specification. Interfaces occur at the highest level of abstraction (user interfaces), at the lowest (function interfaces), and at levels in between (class interfaces, library interfaces, etc.). Regardless of whether you work with end users to specify how they'll interact with a system, collaborate with developers to specify an API, or declare functions private to a class, interface design is an important part of your job. If you do it well, your interfaces will be a pleasure to use and will actually boost productivity. If you do it poorly, your interfaces will be a source of frustration and errors.</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Good interfaces are:</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Good interfaces are:</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>* '''Easy to use correctly.''' People using a well-designed interface almost always use the interface correctly, because that's the path of least resistance. In a GUI, they almost always click on the right icon, button, or menu entry, because it's the obvious and easy thing to do. In an API, they almost always pass the correct parameters with the correct <del style="color: red; font-weight: bold; text-decoration: none;">types and </del>values, because<del style="color: red; font-weight: bold; text-decoration: none;">, again, it</del>'s <del style="color: red; font-weight: bold; text-decoration: none;">obvious and easy</del>. With interfaces that are easy to use correctly, ''things just work.''</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>* '''Easy to use correctly.''' People using a well-designed interface almost always use the interface correctly, because that's the path of least resistance. In a GUI, they almost always click on the right icon, button, or menu entry, because it's the obvious and easy thing to do. In an API, they almost always pass the correct parameters with the correct values, because <ins style="color: red; font-weight: bold; text-decoration: none;">that's what</ins>'s <ins style="color: red; font-weight: bold; text-decoration: none;">most natural</ins>. With interfaces that are easy to use correctly, ''things just work.''</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>* '''Hard to use incorrectly.''' Good interfaces anticipate mistakes people might make<del style="color: red; font-weight: bold; text-decoration: none;">, </del>and <del style="color: red; font-weight: bold; text-decoration: none;">they </del>make them difficult -- ideally impossible -- to commit. A GUI might disable or remove commands that make no sense in the current context, for example, <del style="color: red; font-weight: bold; text-decoration: none;">and </del>an API might <del style="color: red; font-weight: bold; text-decoration: none;">allow </del>parameters to be passed in any order <del style="color: red; font-weight: bold; text-decoration: none;">to eliminate argument-ordering problems</del>.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>* '''Hard to use incorrectly.''' Good interfaces anticipate mistakes people might make and make them difficult -- ideally impossible -- to commit. A GUI might disable or remove commands that make no sense in the current context, for example, <ins style="color: red; font-weight: bold; text-decoration: none;">or </ins>an API might <ins style="color: red; font-weight: bold; text-decoration: none;">eliminate argument-ordering problems by allowing </ins>parameters to be passed in any order.</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>A good way to design interfaces that are easy to use correctly is to <del style="color: red; font-weight: bold; text-decoration: none;">''</del>exercise them before they exist<del style="color: red; font-weight: bold; text-decoration: none;">''</del>. Mock up a GUI -- possibly on a whiteboard or using index cards on a table -- and play with it before <del style="color: red; font-weight: bold; text-decoration: none;">any of </del>the underlying code has been created. Write calls to an API before the functions have been declared. Walk through common use cases and specify how you ''want'' the interface to behave. What do you ''want'' to be able to click on? What do you ''want'' to be able to pass? Easy to use interfaces seem natural, because they let you do what you want to do. You're more likely to come up with such interfaces if you develop them from <del style="color: red; font-weight: bold; text-decoration: none;">the </del>user's point of view. (This perspective is one of the strengths of test-first programming.)</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>A good way to design interfaces that are easy to use correctly is to exercise them before they exist. Mock up a GUI -- possibly on a whiteboard or using index cards on a table -- and play with it before the underlying code has been created. Write calls to an API before the functions have been declared. Walk through common use cases and specify how you ''want'' the interface to behave. What do you ''want'' to be able to click on? What do you ''want'' to be able to pass? Easy to use interfaces seem natural, because they let you do what you want to do. You're more likely to come up with such interfaces if you develop them from <ins style="color: red; font-weight: bold; text-decoration: none;">a </ins>user's point of view. (This perspective is one of the strengths of test-first programming.)</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>Making interfaces hard to use incorrectly requires two things. First, you must anticipate errors users might <del style="color: red; font-weight: bold; text-decoration: none;">inadvertently </del>make and find ways to prevent them. Second, you must observe how an interface is misused during early release and modify the interface -- yes, modify the interface! -- to prevent such errors <del style="color: red; font-weight: bold; text-decoration: none;">before wider deployment</del>. The best way to prevent incorrect use is to make such use impossible. If users keep wanting to undo an irrevocable action, try to make the action revocable. If they keep passing the wrong value to an API, do your best to modify the API to take the values users want to pass.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Making interfaces hard to use incorrectly requires two things. First, you must anticipate errors users might make and find ways to prevent them. Second, you must observe how an interface is misused during early release and modify the interface -- yes, modify the interface! -- to prevent such errors. The best way to prevent incorrect use is to make such use impossible. If users keep wanting to undo an irrevocable action, try to make the action revocable. If they keep passing the wrong value to an API, do your best to modify the API to take the values <ins style="color: red; font-weight: bold; text-decoration: none;">that </ins>users want to pass.</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Above all, remember that interfaces exist for the convenience of their users, not their implementers.</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Above all, remember that interfaces exist for the convenience of their users, not their implementers.</div></td></tr> </table>

ScottMeyers http://commons.oreilly.com/wiki/index.php?title=Make_Interfaces_Easy_to_Use_Correctly_and_Hard_to_Use_Incorrectly&diff=12968&oldid=prev 2008-11-11T01:25:03Z

<p></p> <table style="background-color: white; color:black;"> <col class='diff-marker' /> <col class='diff-content' /> <col class='diff-marker' /> <col class='diff-content' /> <tr> <td colspan='2' style="background-color: white; color:black;">←Older revision</td> <td colspan='2' style="background-color: white; color:black;">Revision as of 01:25, 11 November 2008</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 1:</td> <td colspan="2" class="diff-lineno">Line 1:</td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>One of the most common tasks in software development is interface specification. Interfaces occur at the highest level of abstraction (user interfaces), at the lowest (function interfaces), and at <del style="color: red; font-weight: bold; text-decoration: none;">numerous </del>levels in between (class interfaces, library interfaces, package interfaces, etc.). Regardless of whether you work with end users to specify how they'll interact with a system under design, <del style="color: red; font-weight: bold; text-decoration: none;">work </del>with other developers to specify an API, or declare functions private to a class you're working on, interface design is an important part of your job. If you do it well, <del style="color: red; font-weight: bold; text-decoration: none;">the resulting </del>interfaces will be a pleasure to use and will actually boost productivity. If you do it poorly, your interfaces will be a source of frustration and errors.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>One of the most common tasks in software development is interface specification. Interfaces occur at the highest level of abstraction (user interfaces), at the lowest (function interfaces), and at levels in between (class interfaces, library interfaces, package interfaces, etc.). Regardless of whether you work with end users to specify how they'll interact with a system under design, <ins style="color: red; font-weight: bold; text-decoration: none;">collaborate </ins>with other developers to specify an API, or declare functions private to a class you're working on, interface design is an important part of your job. If you do it well, <ins style="color: red; font-weight: bold; text-decoration: none;">your </ins>interfaces will be a pleasure to use and will actually boost productivity. If you do it poorly, your interfaces will be a source of frustration and errors.</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>Good interfaces <del style="color: red; font-weight: bold; text-decoration: none;">have two crucial characteristics</del>:</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Good interfaces <ins style="color: red; font-weight: bold; text-decoration: none;">are</ins>:</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>* '''<del style="color: red; font-weight: bold; text-decoration: none;">They're easy </del>to use correctly.''' People using a well-designed interface almost always use the interface correctly, because that's the path of least resistance. In a GUI, they almost always click on the right icon, button, or menu entry, because it's the obvious and easy thing to do. In an API, they almost always pass the correct parameters with the correct types and values, because, again, it's obvious and easy. With interfaces that are easy to use correctly, ''things just work.''</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>* '''<ins style="color: red; font-weight: bold; text-decoration: none;">Easy </ins>to use correctly.''' People using a well-designed interface almost always use the interface correctly, because that's the path of least resistance. In a GUI, they almost always click on the right icon, button, or menu entry, because it's the obvious and easy thing to do. In an API, they almost always pass the correct parameters with the correct types and values, because, again, it's obvious and easy. With interfaces that are easy to use correctly, ''things just work.''</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>* '''<del style="color: red; font-weight: bold; text-decoration: none;">They're hard </del>to use incorrectly.''' Good interfaces anticipate mistakes people might make, and they make them difficult -- ideally impossible -- to commit. A GUI might disable or remove commands that make no sense in the current context, for example, and an API might allow parameters to be passed in any order to eliminate <del style="color: red; font-weight: bold; text-decoration: none;">&quot;parameters passed out of order&quot; </del>problems.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>* '''<ins style="color: red; font-weight: bold; text-decoration: none;">Hard </ins>to use incorrectly.''' Good interfaces anticipate mistakes people might make, and they make them difficult -- ideally impossible -- to commit. A GUI might disable or remove commands that make no sense in the current context, for example, and an API might allow parameters to be passed in any order to eliminate <ins style="color: red; font-weight: bold; text-decoration: none;">argument-ordering </ins>problems.</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>A good way to design interfaces that are easy to use correctly is to ''exercise them before they exist''. Mock up a GUI -- possibly on a whiteboard or using index cards on a table -- and play with it before any of the underlying code has been created. Write calls to an API before <del style="color: red; font-weight: bold; text-decoration: none;">any of </del>the functions have been declared. Walk through <del style="color: red; font-weight: bold; text-decoration: none;">various </del>common use cases and specify how you ''want'' the interface to behave. What do you ''want'' to be able to click on? What do you ''want'' to be able to pass? Easy to use interfaces seem natural, because they let you do what you want to do. You're more likely to come up with such interfaces if you develop them from the user's point of view. (<del style="color: red; font-weight: bold; text-decoration: none;">Such a </del>perspective is one of the strengths of test-first programming.)</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>A good way to design interfaces that are easy to use correctly is to ''exercise them before they exist''. Mock up a GUI -- possibly on a whiteboard or using index cards on a table -- and play with it before any of the underlying code has been created. Write calls to an API before the functions have been declared. Walk through common use cases and specify how you ''want'' the interface to behave. What do you ''want'' to be able to click on? What do you ''want'' to be able to pass? Easy to use interfaces seem natural, because they let you do what you want to do. You're more likely to come up with such interfaces if you develop them from the user's point of view. (<ins style="color: red; font-weight: bold; text-decoration: none;">This </ins>perspective is one of the strengths of test-first programming.)</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>Making interfaces hard to use incorrectly requires two things. First, you must <del style="color: red; font-weight: bold; text-decoration: none;">''</del>anticipate errors <del style="color: red; font-weight: bold; text-decoration: none;">that </del>users might inadvertently make<del style="color: red; font-weight: bold; text-decoration: none;">,'' </del>and <del style="color: red; font-weight: bold; text-decoration: none;">you must </del>find ways to prevent <del style="color: red; font-weight: bold; text-decoration: none;">such errors</del>. Second, you must <del style="color: red; font-weight: bold; text-decoration: none;">''</del>observe how <del style="color: red; font-weight: bold; text-decoration: none;">the </del>interface is misused<del style="color: red; font-weight: bold; text-decoration: none;">'' </del>during early release<del style="color: red; font-weight: bold; text-decoration: none;">, </del>and <del style="color: red; font-weight: bold; text-decoration: none;">you must be willing to </del>modify the interface -- yes, modify the interface! -- to prevent such errors before <del style="color: red; font-weight: bold; text-decoration: none;">deploying the interface further</del>. The best way to prevent incorrect use is to make such use impossible. If users keep wanting to undo an irrevocable action, make the action revocable<del style="color: red; font-weight: bold; text-decoration: none;">! </del> If they keep passing the wrong value to an API, modify the API to take the <del style="color: red; font-weight: bold; text-decoration: none;">kind of value </del>users want to pass<del style="color: red; font-weight: bold; text-decoration: none;">! </del></div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Making interfaces hard to use incorrectly requires two things. First, you must anticipate errors users might inadvertently make and find ways to prevent <ins style="color: red; font-weight: bold; text-decoration: none;">them</ins>. Second, you must observe how <ins style="color: red; font-weight: bold; text-decoration: none;">an </ins>interface is misused during early release and modify the interface -- yes, modify the interface! -- to prevent such errors before <ins style="color: red; font-weight: bold; text-decoration: none;">wider deployment</ins>. The best way to prevent incorrect use is to make such use impossible. If users keep wanting to undo an irrevocable action, <ins style="color: red; font-weight: bold; text-decoration: none;">try to </ins>make the action revocable<ins style="color: red; font-weight: bold; text-decoration: none;">. </ins> If they keep passing the wrong value to an API, <ins style="color: red; font-weight: bold; text-decoration: none;">do your best to </ins>modify the API to take the <ins style="color: red; font-weight: bold; text-decoration: none;">values </ins>users want to pass<ins style="color: red; font-weight: bold; text-decoration: none;">.</ins></div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Above all, remember that interfaces exist for the convenience of their users, not their implementers.</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Above all, remember that interfaces exist for the convenience of their users, not their implementers.</div></td></tr> </table>

ScottMeyers http://commons.oreilly.com/wiki/index.php?title=Make_Interfaces_Easy_to_Use_Correctly_and_Hard_to_Use_Incorrectly&diff=12967&oldid=prev 2008-11-11T00:01:11Z

<p></p> <table style="background-color: white; color:black;"> <col class='diff-marker' /> <col class='diff-content' /> <col class='diff-marker' /> <col class='diff-content' /> <tr> <td colspan='2' style="background-color: white; color:black;">←Older revision</td> <td colspan='2' style="background-color: white; color:black;">Revision as of 00:01, 11 November 2008</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 9:</td> <td colspan="2" class="diff-lineno">Line 9:</td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>A good way to design interfaces that are easy to use correctly is to ''exercise them before they exist''. Mock up a GUI -- possibly on a whiteboard or using index cards on a table -- and play with it before any of the underlying code has been created. Write calls to an API before any of the functions have been declared. Walk through various common use cases and specify how you ''want'' the interface to behave. What do you ''want'' to be able to click on? What do you ''want'' to be able to pass? Easy to use interfaces seem natural, because they let you do what you want to do. You're more likely to come up with such interfaces if you develop them from the user's point of view. (Such a perspective is one of the strengths of test-first programming.)</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>A good way to design interfaces that are easy to use correctly is to ''exercise them before they exist''. Mock up a GUI -- possibly on a whiteboard or using index cards on a table -- and play with it before any of the underlying code has been created. Write calls to an API before any of the functions have been declared. Walk through various common use cases and specify how you ''want'' the interface to behave. What do you ''want'' to be able to click on? What do you ''want'' to be able to pass? Easy to use interfaces seem natural, because they let you do what you want to do. You're more likely to come up with such interfaces if you develop them from the user's point of view. (Such a perspective is one of the strengths of test-first programming.)</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>Making interfaces hard to use incorrectly requires two things. First, you must ''anticipate errors that users might inadvertently make,'' and you must find ways to prevent such errors. Second, you must ''observe how the interface is misused'' during early release, and you must be willing to modify the interface -- yes, modify the interface! -- to prevent such errors before deploying the interface further. The best way to prevent incorrect use is to make <del style="color: red; font-weight: bold; text-decoration: none;">it </del>impossible. If users keep wanting to undo an irrevocable action, make <del style="color: red; font-weight: bold; text-decoration: none;">it </del>revocable! If they keep passing the wrong value to an API, modify the API to take the kind of value users want to pass! <del style="color: red; font-weight: bold; text-decoration: none;">Interfaces </del>exist for the convenience of their users, not their implementers.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Making interfaces hard to use incorrectly requires two things. First, you must ''anticipate errors that users might inadvertently make,'' and you must find ways to prevent such errors. Second, you must ''observe how the interface is misused'' during early release, and you must be willing to modify the interface -- yes, modify the interface! -- to prevent such errors before deploying the interface further. The best way to prevent incorrect use is to make <ins style="color: red; font-weight: bold; text-decoration: none;">such use </ins>impossible. If users keep wanting to undo an irrevocable action, make <ins style="color: red; font-weight: bold; text-decoration: none;">the action </ins>revocable! If they keep passing the wrong value to an API, modify the API to take the kind of value users want to pass! </div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>&#160;</div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">Above all, remember that interfaces </ins>exist for the convenience of their users, not their implementers.</div></td></tr> </table>

ScottMeyers http://commons.oreilly.com/wiki/index.php?title=Make_Interfaces_Easy_to_Use_Correctly_and_Hard_to_Use_Incorrectly&diff=12966&oldid=prev 2008-11-10T23:59:18Z

<p></p> <table style="background-color: white; color:black;"> <col class='diff-marker' /> <col class='diff-content' /> <col class='diff-marker' /> <col class='diff-content' /> <tr> <td colspan='2' style="background-color: white; color:black;">←Older revision</td> <td colspan='2' style="background-color: white; color:black;">Revision as of 23:59, 10 November 2008</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 9:</td> <td colspan="2" class="diff-lineno">Line 9:</td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>A good way to design interfaces that are easy to use correctly is to ''exercise them before they exist''. Mock up a GUI -- possibly on a whiteboard or using index cards on a table -- and play with it before any of the underlying code has been created. Write calls to an API before any of the functions have been declared. Walk through various common use cases and specify how you ''want'' the interface to behave. What do you ''want'' to be able to click on? What do you ''want'' to be able to pass? Easy to use interfaces seem natural, because they let you do what you want to do. You're more likely to come up with such interfaces if you develop them from the user's point of view. (Such a perspective is one of the strengths of test-first programming.)</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>A good way to design interfaces that are easy to use correctly is to ''exercise them before they exist''. Mock up a GUI -- possibly on a whiteboard or using index cards on a table -- and play with it before any of the underlying code has been created. Write calls to an API before any of the functions have been declared. Walk through various common use cases and specify how you ''want'' the interface to behave. What do you ''want'' to be able to click on? What do you ''want'' to be able to pass? Easy to use interfaces seem natural, because they let you do what you want to do. You're more likely to come up with such interfaces if you develop them from the user's point of view. (Such a perspective is one of the strengths of test-first programming.)</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>Making interfaces hard to use incorrectly requires two things. First, you must ''anticipate errors that users might inadvertently make,'' and you must find ways to prevent such errors. Second, you must ''observe how the interface is misused'' during early release, and you must be willing to modify the interface -- yes, modify the interface! -- to prevent such errors before deploying the interface further.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Making interfaces hard to use incorrectly requires two things. First, you must ''anticipate errors that users might inadvertently make,'' and you must find ways to prevent such errors. Second, you must ''observe how the interface is misused'' during early release, and you must be willing to modify the interface -- yes, modify the interface! -- to prevent such errors before deploying the interface further<ins style="color: red; font-weight: bold; text-decoration: none;">. The best way to prevent incorrect use is to make it impossible. If users keep wanting to undo an irrevocable action, make it revocable! If they keep passing the wrong value to an API, modify the API to take the kind of value users want to pass! Interfaces exist for the convenience of their users, not their implementers</ins>.</div></td></tr> <!-- diff cache key wikicontent:diff:version:1.11a:oldid:12965:newid:12966 --> </table>

ScottMeyers http://commons.oreilly.com/wiki/index.php?title=Make_Interfaces_Easy_to_Use_Correctly_and_Hard_to_Use_Incorrectly&diff=12965&oldid=prev 2008-11-10T23:55:24Z

<p></p> <table style="background-color: white; color:black;"> <col class='diff-marker' /> <col class='diff-content' /> <col class='diff-marker' /> <col class='diff-content' /> <tr> <td colspan='2' style="background-color: white; color:black;">←Older revision</td> <td colspan='2' style="background-color: white; color:black;">Revision as of 23:55, 10 November 2008</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 1:</td> <td colspan="2" class="diff-lineno">Line 1:</td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>One of the most common tasks <del style="color: red; font-weight: bold; text-decoration: none;">undertaken during </del>software development is interface specification. Interfaces occur at the highest level of abstraction (user interfaces), at the lowest (function interfaces), and at numerous levels in between (class interfaces, library interfaces, package interfaces, etc.). Regardless of whether you<del style="color: red; font-weight: bold; text-decoration: none;">'re working </del>with end users to specify how they'll interact with a system under design, <del style="color: red; font-weight: bold; text-decoration: none;">working </del>with other developers to specify an API, or <del style="color: red; font-weight: bold; text-decoration: none;">declaring </del>functions private to a class you're working on, interface design <del style="color: red; font-weight: bold; text-decoration: none;">will be </del>an important part of your job. If you do it well, the resulting interfaces will be a pleasure to use and will actually boost productivity. If you do it poorly, your interfaces will be a <del style="color: red; font-weight: bold; text-decoration: none;">constant </del>source of frustration and errors.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>One of the most common tasks <ins style="color: red; font-weight: bold; text-decoration: none;">in </ins>software development is interface specification. Interfaces occur at the highest level of abstraction (user interfaces), at the lowest (function interfaces), and at numerous levels in between (class interfaces, library interfaces, package interfaces, etc.). Regardless of whether you <ins style="color: red; font-weight: bold; text-decoration: none;">work </ins>with end users to specify how they'll interact with a system under design, <ins style="color: red; font-weight: bold; text-decoration: none;"> work </ins>with other developers to specify an API, or <ins style="color: red; font-weight: bold; text-decoration: none;">declare </ins>functions private to a class you're working on, interface design <ins style="color: red; font-weight: bold; text-decoration: none;">is </ins>an important part of your job. If you do it well, the resulting interfaces will be a pleasure to use and will actually boost productivity. If you do it poorly, your interfaces will be a source of frustration and errors.</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Good interfaces have two crucial characteristics:</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Good interfaces have two crucial characteristics:</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>* '''They're easy to use correctly.''' People using a well-designed interface almost always use the interface correctly, because that's the path of least resistance. In a GUI, they almost always click on the right icon, button, or menu entry, because it's the <del style="color: red; font-weight: bold; text-decoration: none;">most </del>obvious and easy thing to do. In an API, they almost always pass the correct parameters with the correct types and values, because, again, it's <del style="color: red; font-weight: bold; text-decoration: none;">the most </del>obvious and easy <del style="color: red; font-weight: bold; text-decoration: none;">thing to do</del>. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>With interfaces that are easy to use correctly, ''things just work.''</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>* '''They're easy to use correctly.''' People using a well-designed interface almost always use the interface correctly, because that's the path of least resistance. In a GUI, they almost always click on the right icon, button, or menu entry, because it's the obvious and easy thing to do. In an API, they almost always pass the correct parameters with the correct types and values, because, again, it's obvious and easy. With interfaces that are easy to use correctly, ''things just work.''</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>* '''They're hard to use incorrectly.''' Good interfaces <del style="color: red; font-weight: bold; text-decoration: none;">are designed to </del>anticipate <del style="color: red; font-weight: bold; text-decoration: none;">the kinds of </del>mistakes people might make and <del style="color: red; font-weight: bold; text-decoration: none;">to </del>make them difficult -- ideally impossible -- to commit. A GUI might disable or remove commands that make no sense in the current context, for example, and an API might allow parameters to be passed in any order to eliminate &quot;parameters passed out of order&quot; problems.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>* '''They're hard to use incorrectly.''' Good interfaces anticipate mistakes people might make<ins style="color: red; font-weight: bold; text-decoration: none;">, </ins>and <ins style="color: red; font-weight: bold; text-decoration: none;">they </ins>make them difficult -- ideally impossible -- to commit. A GUI might disable or remove commands that make no sense in the current context, for example, and an API might allow parameters to be passed in any order to eliminate &quot;parameters passed out of order&quot; problems.</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div><del style="color: red; font-weight: bold; text-decoration: none;">One of the best ways </del>to design interfaces that are easy to use correctly is to ''exercise them before they exist''. <del style="color: red; font-weight: bold; text-decoration: none;">That is, mock </del>up a GUI -- possibly on a whiteboard or using index cards on a table -- and play with it before any of the underlying code has been created. Write calls to an API before any of the functions have been declared. Walk through various common use cases and specify how you ''want'' the interface to behave. What do you ''want'' to be able to click on? What do you ''want'' to be able to pass? Easy to use interfaces seem natural, because they let you <del style="color: red; font-weight: bold; text-decoration: none;">-- they ''encourage'' you -- to </del>do what you want to do. You're more likely to come up with such interfaces if<del style="color: red; font-weight: bold; text-decoration: none;">, from the get-go, </del>you develop them from the user's point of view. (Such a <del style="color: red; font-weight: bold; text-decoration: none;">point of view </del>is one of the strengths of test-first <del style="color: red; font-weight: bold; text-decoration: none;">development</del>.)</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div><ins style="color: red; font-weight: bold; text-decoration: none;">A good way </ins>to design interfaces that are easy to use correctly is to ''exercise them before they exist''. <ins style="color: red; font-weight: bold; text-decoration: none;">Mock </ins>up a GUI -- possibly on a whiteboard or using index cards on a table -- and play with it before any of the underlying code has been created. Write calls to an API before any of the functions have been declared. Walk through various common use cases and specify how you ''want'' the interface to behave. What do you ''want'' to be able to click on? What do you ''want'' to be able to pass? Easy to use interfaces seem natural, because they let you <ins style="color: red; font-weight: bold; text-decoration: none;"> </ins>do what you want to do. You're more likely to come up with such interfaces if you develop them from the user's point of view. (Such a <ins style="color: red; font-weight: bold; text-decoration: none;">perspective </ins>is one of the strengths of test-first <ins style="color: red; font-weight: bold; text-decoration: none;">programming</ins>.)</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>Making interfaces <del style="color: red; font-weight: bold; text-decoration: none;">that are </del>hard to use incorrectly requires two things. First, you must ''anticipate errors that users might inadvertently make,'' and you must find ways <del style="color: red; font-weight: bold; text-decoration: none;">for the interface </del>to prevent such errors. Second, you must ''observe how the interface is misused'' during early <del style="color: red; font-weight: bold; text-decoration: none;">usage</del>, and you must be willing to modify the interface -- yes, modify the interface! -- to prevent such errors before <del style="color: red; font-weight: bold; text-decoration: none;">you deploy </del>the interface further.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Making interfaces hard to use incorrectly requires two things. First, you must ''anticipate errors that users might inadvertently make,'' and you must find ways to prevent such errors. Second, you must ''observe how the interface is misused'' during early <ins style="color: red; font-weight: bold; text-decoration: none;">release</ins>, and you must be willing to modify the interface -- yes, modify the interface! -- to prevent such errors before <ins style="color: red; font-weight: bold; text-decoration: none;">deploying </ins>the interface further.</div></td></tr> </table>

ScottMeyers http://commons.oreilly.com/wiki/index.php?title=Make_Interfaces_Easy_to_Use_Correctly_and_Hard_to_Use_Incorrectly&diff=12964&oldid=prev 2008-11-10T23:43:53Z

<p></p> <table style="background-color: white; color:black;"> <col class='diff-marker' /> <col class='diff-content' /> <col class='diff-marker' /> <col class='diff-content' /> <tr> <td colspan='2' style="background-color: white; color:black;">←Older revision</td> <td colspan='2' style="background-color: white; color:black;">Revision as of 23:43, 10 November 2008</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 7:</td> <td colspan="2" class="diff-lineno">Line 7:</td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>* '''They're hard to use incorrectly.''' Good interfaces are designed to anticipate the kinds of mistakes people might make and to make them difficult -- ideally impossible -- to commit. A GUI might disable or remove commands that make no sense in the current context, for example, and an API might allow parameters to be passed in any order to eliminate &quot;parameters passed out of order&quot; problems.</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>* '''They're hard to use incorrectly.''' Good interfaces are designed to anticipate the kinds of mistakes people might make and to make them difficult -- ideally impossible -- to commit. A GUI might disable or remove commands that make no sense in the current context, for example, and an API might allow parameters to be passed in any order to eliminate &quot;parameters passed out of order&quot; problems.</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>One of the best ways to design interfaces that are easy to use correctly is to exercise them before they exist. That is, mock up a GUI -- possibly on a whiteboard or using index cards on a table -- and play with it before any of the underlying code has been created. Write calls to an API before any of the functions have been declared. Walk through various common use cases and specify how you ''want'' the interface to behave. What do you ''want'' to be able to click on? What do you ''want'' to be able to pass? Easy to use interfaces seem natural, because they let you -- they ''encourage'' you -- to do what you want to do. You're more likely to come up with such interfaces if, from the get-go, you develop them from the user's point of view. (Such a point of view is one of the strengths of test-first development.)</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>One of the best ways to design interfaces that are easy to use correctly is to <ins style="color: red; font-weight: bold; text-decoration: none;">''</ins>exercise them before they exist<ins style="color: red; font-weight: bold; text-decoration: none;">''</ins>. That is, mock up a GUI -- possibly on a whiteboard or using index cards on a table -- and play with it before any of the underlying code has been created. Write calls to an API before any of the functions have been declared. Walk through various common use cases and specify how you ''want'' the interface to behave. What do you ''want'' to be able to click on? What do you ''want'' to be able to pass? Easy to use interfaces seem natural, because they let you -- they ''encourage'' you -- to do what you want to do. You're more likely to come up with such interfaces if, from the get-go, you develop them from the user's point of view. (Such a point of view is one of the strengths of test-first development.)</div></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>Making interfaces that are hard to use incorrectly requires two things. First, you must anticipate errors that users might inadvertently make, and you must find ways for the interface to prevent such errors. Second, you must observe how the interface is misused during early usage, and you must be willing to modify the interface -- yes, modify the interface! -- to prevent such errors before you deploy the interface further.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Making interfaces that are hard to use incorrectly requires two things. First, you must <ins style="color: red; font-weight: bold; text-decoration: none;">''</ins>anticipate errors that users might inadvertently make,<ins style="color: red; font-weight: bold; text-decoration: none;">'' </ins>and you must find ways for the interface to prevent such errors. Second, you must <ins style="color: red; font-weight: bold; text-decoration: none;">''</ins>observe how the interface is misused<ins style="color: red; font-weight: bold; text-decoration: none;">'' </ins>during early usage, and you must be willing to modify the interface -- yes, modify the interface! -- to prevent such errors before you deploy the interface further.</div></td></tr> </table>

ScottMeyers http://commons.oreilly.com/wiki/index.php?title=Make_Interfaces_Easy_to_Use_Correctly_and_Hard_to_Use_Incorrectly&diff=12963&oldid=prev 2008-11-10T23:42:33Z

<p></p> <table style="background-color: white; color:black;"> <col class='diff-marker' /> <col class='diff-content' /> <col class='diff-marker' /> <col class='diff-content' /> <tr> <td colspan='2' style="background-color: white; color:black;">←Older revision</td> <td colspan='2' style="background-color: white; color:black;">Revision as of 23:42, 10 November 2008</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 8:</td> <td colspan="2" class="diff-lineno">Line 8:</td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"></td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>One of the best ways to design interfaces that are easy to use correctly is to exercise them before they exist. That is, mock up a GUI -- possibly on a whiteboard or using index cards on a table -- and play with it before any of the underlying code has been created. Write calls to an API before any of the functions have been declared. Walk through various common use cases and specify how you ''want'' the interface to behave. What do you ''want'' to be able to click on? What do you ''want'' to be able to pass? Easy to use interfaces seem natural, because they let you -- they ''encourage'' you -- to do what you want to do. You're more likely to come up with such interfaces if, from the get-go, you develop them from the user's point of view. (Such a point of view is one of the strengths of test-first development.)</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>One of the best ways to design interfaces that are easy to use correctly is to exercise them before they exist. That is, mock up a GUI -- possibly on a whiteboard or using index cards on a table -- and play with it before any of the underlying code has been created. Write calls to an API before any of the functions have been declared. Walk through various common use cases and specify how you ''want'' the interface to behave. What do you ''want'' to be able to click on? What do you ''want'' to be able to pass? Easy to use interfaces seem natural, because they let you -- they ''encourage'' you -- to do what you want to do. You're more likely to come up with such interfaces if, from the get-go, you develop them from the user's point of view. (Such a point of view is one of the strengths of test-first development.)</div></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"></td></tr> <tr><td colspan="2">&nbsp;</td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Making interfaces that are hard to use incorrectly requires two things. First, you must anticipate errors that users might inadvertently make, and you must find ways for the interface to prevent such errors. Second, you must observe how the interface is misused during early usage, and you must be willing to modify the interface -- yes, modify the interface! -- to prevent such errors before you deploy the interface further.</div></td></tr> </table>

ScottMeyers