The Golden Rule of API Design - Revision history

http://commons.oreilly.com/wiki/index.php?title=The_Golden_Rule_of_API_Design&action=history&feed=atom The Golden Rule of API Design - Revision history 2013-05-21T10:13:13Z Revision history for this page on the wiki MediaWiki 1.11.0 http://commons.oreilly.com/wiki/index.php?title=The_Golden_Rule_of_API_Design&diff=24646&oldid=prev Kevlin at 21:46, 6 July 2009 2009-07-06T21:46:50Z

<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 21:46, 6 July 2009</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>API design is tough, particularly in the large. If you are designing an API <del style="color: red; font-weight: bold; text-decoration: none;">which </del>is going to have hundreds or thousands of users, you have to think about how you might change it in the future and whether your changes might break client code. Beyond that, you have to think about how users of your API affect you. If one of your API classes uses one of its own methods internally, you have to remember that a user could subclass your class and override it, and that could be disastrous. You wouldn't be able to change that method because some of your users have given it a different meaning. Your future internal implementation choices are at the mercy of your users.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>API design is tough, particularly in the large. If you are designing an API <ins style="color: red; font-weight: bold; text-decoration: none;">that </ins>is going to have hundreds or thousands of users, you have to think about how you might change it in the future and whether your changes might break client code. Beyond that, you have to think about how users of your API affect you. If one of your API classes uses one of its own methods internally, you have to remember that a user could subclass your class and override it, and that could be disastrous. You wouldn't be able to change that method because some of your users have given it a different meaning. Your future internal implementation choices are at the mercy of your users.</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>API developers solve this problem in various ways, but the easiest way is to lock down the API. If you are working in Java you might be tempted to make most of your classes and methods final. In C#, you might make your classes and methods sealed. Regardless of the language you are using, you might be tempted to present your API through a singleton or use static factory methods so that you can guard it from people who might override behavior and use your code in ways which may constrain your choices later. This all seems reasonable, but is it really?</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>API developers solve this problem in various ways, but the easiest way is to lock down the API. If you are working in Java you might be tempted to make most of your classes and methods <ins style="color: red; font-weight: bold; text-decoration: none;"><code></ins>final<ins style="color: red; font-weight: bold; text-decoration: none;"></code></ins>. In C#, you might make your classes and methods <ins style="color: red; font-weight: bold; text-decoration: none;"><code></ins>sealed<ins style="color: red; font-weight: bold; text-decoration: none;"></code></ins>. Regardless of the language you are using, you might be tempted to present your API through a singleton or use <ins style="color: red; font-weight: bold; text-decoration: none;"><code></ins>static<ins style="color: red; font-weight: bold; text-decoration: none;"></code> </ins>factory methods so that you can guard it from people who might override behavior and use your code in ways which may constrain your choices later. This all seems reasonable, but is it really?</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>Over the past decade, we've gradually realized that unit testing is an extremely important part of practice, but that lesson has not completely permeated the industry. The evidence is all around us. Take an arbitrary <del style="color: red; font-weight: bold; text-decoration: none;">class </del>untested class <del style="color: red; font-weight: bold; text-decoration: none;">which </del>uses a third-party API and try to write unit tests for it. Most of the time, you'll run into trouble. You'll find that the code using the API is stuck to it like glue. There's no way to impersonate the API classes so that you can sense your code's interactions with them, or supply return values for testing. </div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Over the past decade, we've gradually realized that unit testing is an extremely important part of practice, but that lesson has not completely permeated the industry. The evidence is all around us. Take an arbitrary untested class <ins style="color: red; font-weight: bold; text-decoration: none;">that </ins>uses a third-party API and try to write unit tests for it. Most of the time, you'll run into trouble. You'll find that the code using the API is stuck to it like glue. There's no way to impersonate the API classes so that you can sense your code's interactions with them, or supply return values for testing. </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>Over time, this will get better, but only if we start to see testing as a real use case when we design APIs. Unfortunately, it's a little bit more involved than just testing our code. That's where the '''Golden Rule of API Design''' fits in: ''It's not enough to write tests for an API you develop<del style="color: red; font-weight: bold; text-decoration: none;">, </del>you have to write unit tests for code that uses your API. When you do, you learn first-hand the hurdles that your users will have to overcome when they try to test their code independently.''</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Over time, this will get better, but only if we start to see testing as a real use case when we design APIs. Unfortunately, it's a little bit more involved than just testing our code. That's where the '''Golden Rule of API Design''' fits in: ''It's not enough to write tests for an API you develop<ins style="color: red; font-weight: bold; text-decoration: none;">; </ins>you have to write unit tests for code that uses your API. When you do, you learn first-hand the hurdles that your users will have to overcome when they try to test their code independently.''</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>There is no one way to make it easy for developers to test code which uses your API. <del style="color: red; font-weight: bold; text-decoration: none;">Static</del>, final, and sealed are not inherently bad constructs. They can be useful at times. But it is important to be aware of the testing issue and to do that, you have to experience it yourself. Once you have, you can approach it as you would any other design challenge.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>There is no one way to make it easy for developers to test code which uses your API. <ins style="color: red; font-weight: bold; text-decoration: none;"><code>static</code></ins>, <ins style="color: red; font-weight: bold; text-decoration: none;"><code></ins>final<ins style="color: red; font-weight: bold; text-decoration: none;"></code></ins>, and <ins style="color: red; font-weight: bold; text-decoration: none;"><code></ins>sealed<ins style="color: red; font-weight: bold; text-decoration: none;"></code> </ins>are not inherently bad constructs. They can be useful at times. But it is important to be aware of the testing issue and to do that, you have to experience it yourself. Once you have, you can approach it as you would any other design challenge.</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>By [[Michael Feathers]]</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>By [[Michael Feathers]]</div></td></tr> <tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"></td></tr> <tr><td colspan="2"> </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"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"></td></tr> <tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"></td></tr> <tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"></td></tr> <tr><td colspan="2"> </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>  </table>

Kevlin http://commons.oreilly.com/wiki/index.php?title=The_Golden_Rule_of_API_Design&diff=24644&oldid=prev Mfeathers at 21:13, 6 July 2009 2009-07-06T21:13:36Z

<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 21:13, 6 July 2009</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>API design is tough, particularly in the large. If you are designing an API which is going to have hundreds or thousands of users, you have to think about how you might change it in the future and whether your changes might break client code. </div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>API design is tough, particularly in the large. If you are designing an API which is going to have hundreds or thousands of users, you have to think about how you might change it in the future and whether your changes might break client code. <ins style="color: red; font-weight: bold; text-decoration: none;">Beyond </ins>that, you have to <ins style="color: red; font-weight: bold; text-decoration: none;">think about how users of </ins>your API <ins style="color: red; font-weight: bold; text-decoration: none;">affect you</ins>. If one of your API classes uses one of its own methods internally, you have to remember that a user could subclass your class and override it, and that could be disastrous. You wouldn't be able to change that method because some of your users have given it a different meaning. Your future internal implementation choices are at the mercy of your users.</div></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div> </div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div></div></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;">You aren't going to be able to freely refactor your API over time, so there are some decisions </del>that <del style="color: red; font-weight: bold; text-decoration: none;">you have to get right in the beginning</del>, <del style="color: red; font-weight: bold; text-decoration: none;">because right or wrong </del>you <del style="color: red; font-weight: bold; text-decoration: none;">are going to </del>have to <del style="color: red; font-weight: bold; text-decoration: none;">live with their consequences for a long while. </del></div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div></div></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div> </div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div></div></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;">Above all, you have to protect </del>your API. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>If one of your API classes uses one of its own methods internally, you have to remember that a user could subclass your class and override it, and that could be disastrous. You wouldn't be able to change that method because some of your users have given it a different meaning. Your future internal implementation choices are at the mercy of your users.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div></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>API developers solve this problem in various ways, but the easiest way is to lock down the API. If you are working in Java you might be tempted to make most of your classes and methods final. In C#, you might make your classes and methods sealed. Regardless of the language you are using, you might be tempted to present your API through a singleton or use static factory methods so that you can guard it from people who might override behavior and use your code in ways which may constrain your choices later. This all seems reasonable, but is it really?</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>API developers solve this problem in various ways, but the easiest way is to lock down the API. If you are working in Java you might be tempted to make most of your classes and methods final. In C#, you might make your classes and methods sealed. Regardless of the language you are using, you might be tempted to present your API through a singleton or use static factory methods so that you can guard it from people who might override behavior and use your code in ways which may constrain your choices later. This all seems reasonable, but is it really?</div></td></tr>  </table>

Mfeathers http://commons.oreilly.com/wiki/index.php?title=The_Golden_Rule_of_API_Design&diff=24643&oldid=prev Mfeathers at 21:09, 6 July 2009 2009-07-06T21:09:58Z

<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 21:09, 6 July 2009</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 11:</td> <td colspan="2" class="diff-lineno">Line 11:</td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Over time, this will get better, but only if we start to see testing as a real use case when we design APIs. Unfortunately, it's a little bit more involved than just testing our code. That's where the '''Golden Rule of API Design''' fits in: ''It's not enough to write tests for an API you develop, you have to write unit tests for code that uses your API. When you do, you learn first-hand the hurdles that your users will have to overcome when they try to test their code independently.''</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Over time, this will get better, but only if we start to see testing as a real use case when we design APIs. Unfortunately, it's a little bit more involved than just testing our code. That's where the '''Golden Rule of API Design''' fits in: ''It's not enough to write tests for an API you develop, you have to write unit tests for code that uses your API. When you do, you learn first-hand the hurdles that your users will have to overcome when they try to test their code independently.''</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>There is no one way to make it easy for developers to test code which uses your API. Static, final, and sealed are not inherently bad constructs. They can be useful at times. But it is important to be aware of the testing issue and to do that, you have to experience it yourself. Once you have, you can approach <del style="color: red; font-weight: bold; text-decoration: none;">the API user testing challenge </del>as you would any other design <del style="color: red; font-weight: bold; text-decoration: none;">issue</del>.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>There is no one way to make it easy for developers to test code which uses your API. Static, final, and sealed are not inherently bad constructs. They can be useful at times. But it is important to be aware of the testing issue and to do that, you have to experience it yourself. Once you have, you can approach <ins style="color: red; font-weight: bold; text-decoration: none;">it </ins>as you would any other design <ins style="color: red; font-weight: bold; text-decoration: none;">challenge</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>By [[Michael Feathers]]</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>By [[Michael Feathers]]</div></td></tr> </table>

Mfeathers http://commons.oreilly.com/wiki/index.php?title=The_Golden_Rule_of_API_Design&diff=24642&oldid=prev Mfeathers at 21:08, 6 July 2009 2009-07-06T21:08:44Z

<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 21:08, 6 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>There is no one way to make it easy for developers to test code which uses your API. Static, final, and sealed are not inherently bad constructs. They can be useful at times. But it is important to be aware of the testing issue and to do that, you have to experience it yourself. Once you have, you can approach the API user testing challenge as you would any other design issue.</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>There is no one way to make it easy for developers to test code which uses your API. Static, final, and sealed are not inherently bad constructs. They can be useful at times. But it is important to be aware of the testing issue and to do that, you have to experience it yourself. Once you have, you can approach the API user testing challenge as you would any other design issue.</div></td></tr> <tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"></td></tr> <tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>By [[Michael Feathers]]</div></td></tr> </table>

Mfeathers http://commons.oreilly.com/wiki/index.php?title=The_Golden_Rule_of_API_Design&diff=24641&oldid=prev Mfeathers at 21:07, 6 July 2009 2009-07-06T21:07: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 21:07, 6 July 2009</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: #eee; color:black; font-size: smaller;"><div>API design is tough, particularly in the large. If you are designing an API which is going to have hundreds or thousands of users, you have to think about how you might change it in the future and whether your changes might break client code. </div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>API design is tough, particularly in the large. If you are designing an API which is going to have hundreds or thousands of users, you have to think about how you might change it in the future and whether your changes might break client code. </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>You aren't going to be able to freely refactor your API over time, so there are some decisions that you have to get right in the beginning, because right or wrong you are going to have to live with their consequences for a long while. <del style="color: red; font-weight: bold; text-decoration: none;"> </del>Above all, you have to protect your API. If one of your API classes uses one of its own methods internally, you have to remember that a user could subclass your class and override it, and that could be disastrous. You wouldn't be able to change that method because some of your users have given it a different meaning. Your future internal implementation choices are at the mercy of your users.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>You aren't going to be able to freely refactor your API over time, so there are some decisions that you have to get right in the beginning, because right or wrong you are going to have to live with their consequences for a long while. </div></td></tr> <tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div> </div></td></tr> <tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Above all, you have to protect your API. If one of your API classes uses one of its own methods internally, you have to remember that a user could subclass your class and override it, and that could be disastrous. You wouldn't be able to change that method because some of your users have given it a different meaning. Your future internal implementation choices are at the mercy of your users.</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>API developers solve this problem in various ways, but the easiest way is to lock down the API. If you are working in Java you might be tempted to make most of your classes and methods final. In C#, you might make your classes and methods sealed. Regardless of the language you are using, you might be tempted to present your API through a singleton or use static factory methods so that you can guard it from people who might override behavior and use your code in ways which may constrain your choices later. This all seems reasonable, but is it really?</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>API developers solve this problem in various ways, but the easiest way is to lock down the API. If you are working in Java you might be tempted to make most of your classes and methods final. In C#, you might make your classes and methods sealed. Regardless of the language you are using, you might be tempted to present your API through a singleton or use static factory methods so that you can guard it from people who might override behavior and use your code in ways which may constrain your choices later. This all seems reasonable, but is it really?</div></td></tr> </table>

Mfeathers http://commons.oreilly.com/wiki/index.php?title=The_Golden_Rule_of_API_Design&diff=24640&oldid=prev Mfeathers at 21:06, 6 July 2009 2009-07-06T21:06:28Z

<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 21:06, 6 July 2009</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: #eee; color:black; font-size: smaller;"><div>API design is tough, particularly in the large. If you are designing an API which is going to have hundreds or thousands of users, you have to think about how you might change it in the future and whether your changes might break client code. </div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>API design is tough, particularly in the large. If you are designing an API which is going to have hundreds or thousands of users, you have to think about how you might change it in the future and whether your changes might break client code. </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>You aren't going to be able to refactor your <del style="color: red; font-weight: bold; text-decoration: none;">AI freely </del>over time, so there are some decisions that you have to get right in the beginning, because right or wrong you are going to have to live with their consequences for a long while. Above all, you have to protect your API. If one of your API classes uses one of its own methods internally, you have to remember that a user could subclass your class and override it, and that could be disastrous. You wouldn't be able to change that method because some of your users have given it a different meaning. Your future internal implementation choices are at the mercy of your users.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>You aren't going to be able to <ins style="color: red; font-weight: bold; text-decoration: none;">freely </ins>refactor your <ins style="color: red; font-weight: bold; text-decoration: none;">API </ins>over time, so there are some decisions that you have to get right in the beginning, because right or wrong you are going to have to live with their consequences for a long while. Above all, you have to protect your API. If one of your API classes uses one of its own methods internally, you have to remember that a user could subclass your class and override it, and that could be disastrous. You wouldn't be able to change that method because some of your users have given it a different meaning. Your future internal implementation choices are at the mercy of your users.</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>API developers solve this problem in various ways, but the easiest way is to lock down the API. If you are working in Java you might be tempted to make most of your classes and methods final. In C#, you might make your classes and methods sealed. Regardless of the language you are using, you might be tempted to present your API through a singleton or use static factory methods so that you can guard it from people who might override behavior and use your code in ways which may constrain your choices later. This all seems reasonable, but is it really?</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>API developers solve this problem in various ways, but the easiest way is to lock down the API. If you are working in Java you might be tempted to make most of your classes and methods final. In C#, you might make your classes and methods sealed. Regardless of the language you are using, you might be tempted to present your API through a singleton or use static factory methods so that you can guard it from people who might override behavior and use your code in ways which may constrain your choices later. This all seems reasonable, but is it really?</div></td></tr>  </table>

Mfeathers http://commons.oreilly.com/wiki/index.php?title=The_Golden_Rule_of_API_Design&diff=24639&oldid=prev Mfeathers at 20:51, 6 July 2009 2009-07-06T20:51:26Z

<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 20:51, 6 July 2009</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>API design is tough, <del style="color: red; font-weight: bold; text-decoration: none;">especially </del>in the large. If you are designing an API which is going to have hundreds or thousands of users, you have to think about how you might change it in the future and whether your changes might break client code. You aren't going to be able to refactor your AI freely over time, so there are some decisions that you have to get right, because right or wrong you are going to have to live with their consequences for a long while. Above all, you have to protect your API. If one of your API classes uses one of its own methods internally, you have to remember that a user could subclass your class and override it, and that could be disastrous. You wouldn't be able to change that method because some of your users have given it a different meaning. Your future internal implementation choices are at the mercy of your users.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>API design is tough, <ins style="color: red; font-weight: bold; text-decoration: none;">particularly </ins>in the large. If you are designing an API which is going to have hundreds or thousands of users, you have to think about how you might change it in the future and whether your changes might break client code. </div></td></tr> <tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div> </div></td></tr> <tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>You aren't going to be able to refactor your AI freely over time, so there are some decisions that you have to get right <ins style="color: red; font-weight: bold; text-decoration: none;">in the beginning</ins>, because right or wrong you are going to have to live with their consequences for a long while. Above all, you have to protect your API. If one of your API classes uses one of its own methods internally, you have to remember that a user could subclass your class and override it, and that could be disastrous. You wouldn't be able to change that method because some of your users have given it a different meaning. Your future internal implementation choices are at the mercy of your users.</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>API developers solve this problem in various ways, but the easiest way is to lock down the API. If you are working in Java you might be tempted to make most of your classes and methods final. In C#, you might make your classes and methods sealed. Regardless of the language you are using, you might be tempted to present your API through a singleton or use static factory methods so that you can guard it from people who might override behavior and use your code in ways which may constrain your choices later. This all seems reasonable, but is it really?</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>API developers solve this problem in various ways, but the easiest way is to lock down the API. If you are working in Java you might be tempted to make most of your classes and methods final. In C#, you might make your classes and methods sealed. Regardless of the language you are using, you might be tempted to present your API through a singleton or use static factory methods so that you can guard it from people who might override behavior and use your code in ways which may constrain your choices later. This all seems reasonable, but is it really?</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>Over the past decade, we've gradually realized that unit testing is an extremely important part of practice, but <del style="color: red; font-weight: bold; text-decoration: none;">the </del>lesson has not completely permeated the industry. The evidence is all around us. Take an arbitrary class untested class which uses a third-party API and try to write unit tests for it. Most of the time, you'll run into trouble. You'll find that the code using the API is stuck to it like glue. There's no way to impersonate the API <del style="color: red; font-weight: bold; text-decoration: none;">class </del>so that you can sense your code's interactions with <del style="color: red; font-weight: bold; text-decoration: none;">it</del>, or supply return values for testing. </div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Over the past decade, we've gradually realized that unit testing is an extremely important part of practice, but <ins style="color: red; font-weight: bold; text-decoration: none;">that </ins>lesson has not completely permeated the industry. The evidence is all around us. Take an arbitrary class untested class which uses a third-party API and try to write unit tests for it. Most of the time, you'll run into trouble. You'll find that the code using the API is stuck to it like glue. There's no way to impersonate the API <ins style="color: red; font-weight: bold; text-decoration: none;">classes </ins>so that you can sense your code's interactions with <ins style="color: red; font-weight: bold; text-decoration: none;">them</ins>, or supply return values for testing. </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>Over time, this will get better, but only if we start to see testing as a real use case when we design APIs. Unfortunately, it's a little bit more involved than just testing our code. That's where the '''Golden Rule of API Design''' fits in: ''It's not enough to write tests for an API you develop, you have to write unit tests for code that uses your API. When you do, you learn first-hand the hurdles that your users will have to overcome when they try to test their code independently.''</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Over time, this will get better, but only if we start to see testing as a real use case when we design APIs. Unfortunately, it's a little bit more involved than just testing our code. That's where the '''Golden Rule of API Design''' fits in: ''It's not enough to write tests for an API you develop, you have to write unit tests for code that uses your API. When you do, you learn first-hand the hurdles that your users will have to overcome when they try to test their code independently.''</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>There is no one way to make it easy for developers to test code which uses your API. Static, final, and sealed are not inherently bad constructs. They can be useful at times. But it is important to be aware of the testing issue and to do that, you have to experience it yourself. Once you have, you can <del style="color: red; font-weight: bold; text-decoration: none;">start to solve </del>the API user testing <del style="color: red; font-weight: bold; text-decoration: none;">issue </del>as you would any other design <del style="color: red; font-weight: bold; text-decoration: none;">challenge</del>.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>There is no one way to make it easy for developers to test code which uses your API. Static, final, and sealed are not inherently bad constructs. They can be useful at times. But it is important to be aware of the testing issue and to do that, you have to experience it yourself. Once you have, you can <ins style="color: red; font-weight: bold; text-decoration: none;">approach </ins>the API user testing <ins style="color: red; font-weight: bold; text-decoration: none;">challenge </ins>as you would any other design <ins style="color: red; font-weight: bold; text-decoration: none;">issue</ins>.</div></td></tr> </table>

Mfeathers http://commons.oreilly.com/wiki/index.php?title=The_Golden_Rule_of_API_Design&diff=24638&oldid=prev Mfeathers at 20:47, 6 July 2009 2009-07-06T20:47:38Z

<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 20:47, 6 July 2009</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 6:</td> <td colspan="2" class="diff-lineno">Line 6:</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>Over time, this will get better, but only if we start to see testing as a real use case when we design APIs. Unfortunately, it's a little bit more involved than just testing our code. That's where the '''Golden Rule of API Design''' fits in: ''It's not enough to write tests for an API you develop, you have to write unit tests for code that uses your API. When you do, you learn first-hand the hurdles that your users will have to overcome when they try to test their code independently.''</div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Over time, this will get better, but only if we start to see testing as a real use case when we design APIs. Unfortunately, it's a little bit more involved than just testing our code. That's where the '''Golden Rule of API Design''' fits in: ''It's not enough to write tests for an API you develop, you have to write unit tests for code that uses your API. When you do, you learn first-hand the hurdles that your users will have to overcome when they try to test their code independently.''</div></td></tr> <tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"></td></tr> <tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>There is no one way to make it easy for developers to test code which uses your API. Static, final, and sealed are not inherently bad constructs. They can be useful at times. But it is important to be aware of the testing issue and to do that, you have to experience it yourself. Once you have, you can start to solve the API user testing issue as you would any other design challenge.</div></td></tr> </table>

Mfeathers http://commons.oreilly.com/wiki/index.php?title=The_Golden_Rule_of_API_Design&diff=24637&oldid=prev Mfeathers at 20:43, 6 July 2009 2009-07-06T20:43:51Z

<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 20:43, 6 July 2009</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 5:</td> <td colspan="2" class="diff-lineno">Line 5:</td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Over the past decade, we've gradually realized that unit testing is an extremely important part of practice, but the lesson has not completely permeated the industry. The evidence is all around us. Take an arbitrary class untested class which uses a third-party API and try to write unit tests for it. Most of the time, you'll run into trouble. You'll find that the code using the API is stuck to it like glue. There's no way to impersonate the API class so that you can sense your code's interactions with it, or supply return values for testing. </div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Over the past decade, we've gradually realized that unit testing is an extremely important part of practice, but the lesson has not completely permeated the industry. The evidence is all around us. Take an arbitrary class untested class which uses a third-party API and try to write unit tests for it. Most of the time, you'll run into trouble. You'll find that the code using the API is stuck to it like glue. There's no way to impersonate the API class so that you can sense your code's interactions with it, or supply return values for testing. </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>Over time, this will get better, but only if we start to see testing as a real use case when we design APIs. Unfortunately, it's a little bit more involved than just testing our code. That's where the Golden Rule of API Design fits in: ''It's not enough to write tests for an API you develop, you have to write unit tests for code that uses your API. When you do, you learn first-hand the hurdles that your users will have to overcome when they try to test their code independently.''</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Over time, this will get better, but only if we start to see testing as a real use case when we design APIs. Unfortunately, it's a little bit more involved than just testing our code. That's where the <ins style="color: red; font-weight: bold; text-decoration: none;">'''</ins>Golden Rule of API Design<ins style="color: red; font-weight: bold; text-decoration: none;">''' </ins>fits in: ''It's not enough to write tests for an API you develop, you have to write unit tests for code that uses your API. When you do, you learn first-hand the hurdles that your users will have to overcome when they try to test their code independently.''</div></td></tr>  </table>

Mfeathers http://commons.oreilly.com/wiki/index.php?title=The_Golden_Rule_of_API_Design&diff=24636&oldid=prev Mfeathers at 20:43, 6 July 2009 2009-07-06T20:43: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 20:43, 6 July 2009</td> </tr> <tr><td colspan="2" class="diff-lineno">Line 5:</td> <td colspan="2" class="diff-lineno">Line 5:</td></tr> <tr><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Over the past decade, we've gradually realized that unit testing is an extremely important part of practice, but the lesson has not completely permeated the industry. The evidence is all around us. Take an arbitrary class untested class which uses a third-party API and try to write unit tests for it. Most of the time, you'll run into trouble. You'll find that the code using the API is stuck to it like glue. There's no way to impersonate the API class so that you can sense your code's interactions with it, or supply return values for testing. </div></td><td class='diff-marker'> </td><td style="background: #eee; color:black; font-size: smaller;"><div>Over the past decade, we've gradually realized that unit testing is an extremely important part of practice, but the lesson has not completely permeated the industry. The evidence is all around us. Take an arbitrary class untested class which uses a third-party API and try to write unit tests for it. Most of the time, you'll run into trouble. You'll find that the code using the API is stuck to it like glue. There's no way to impersonate the API class so that you can sense your code's interactions with it, or supply return values for testing. </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>Over time, this will get better, but only if we start to see testing as a real use case when we design APIs. Unfortunately, it's a little bit more involved than just testing our code. That's where the Golden Rule of API Design fits in:</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div>Over time, this will get better, but only if we start to see testing as a real use case when we design APIs. Unfortunately, it's a little bit more involved than just testing our code. That's where the Golden Rule of API Design fits in: ''It's not enough to write tests for an API you develop, you have to write unit tests for code that uses your API. When you do, you learn first-hand the hurdles that your users will have to overcome when they try to test their code independently.<ins style="color: red; font-weight: bold; text-decoration: none;">''</ins></div></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div> </div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div></div></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;">'The Golden Rule of API Design''' </del></div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div></div></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div> </div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div></div></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>It's not enough to write tests for an API you develop, you have to write unit tests for code that uses your API.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div></div></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div> </div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div></div></td></tr> <tr><td class='diff-marker'>-</td><td style="background: #ffa; color:black; font-size: smaller;"><div>When you do, you learn first-hand the hurdles that your users will have to overcome when they try to test their code independently.</div></td><td class='diff-marker'>+</td><td style="background: #cfc; color:black; font-size: smaller;"><div></div></td></tr>  </table>

Mfeathers