Practices and tools for building better API (JFall 2013)
•
9 gostaram•4,547 visualizações
Een belangrijke voorwaarde om goede en leesbare Java code te schrijven is om gebruik te maken van een goede API. Een goede API helpt ontwikkelaars om sneller hoogwaardige code te schrijven. Het ontwerp van een API is daarom belangrijk, zeker als er grotere systemen worden gerealiseerd in teamverband. Moderne ontwikkeltools als Eclipse, IntelliJ IDEA en FindBugs helpen met het schrijven van goede API, en het detecteren van slecht gebruik. Deze sessie gaat in op de laatste ontwikkelingen en mogelijkheden, inclusief nieuwe taalmogelijkheden in Java 8. Er wordt hierbij gebruik gemaakt van praktische situaties en concrete codevoorbeelden, gebaseerd op echte ervaringen in grote codebases. Met praktische tips en toegankelijke tools kan al een grote stap gemaakt worden om in de praktijk beter met API ontwerp om te gaan!
Recomendados
Mais conteúdo relacionado
Mais procurados
Mais procurados (20)
Semelhante a Practices and tools for building better API (JFall 2013)
Semelhante a Practices and tools for building better API (JFall 2013) (20)
Último
Último (20)
Practices and tools for building better API (JFall 2013)
- 1. Practices and Tools for Building Better APIs @PeterHendriks80, +PeterHendriks
- 2. Objectives of this talk • API from a Java app developer perspective ! • • • • Why API is important What makes a better API Practical tips and tools Measuring your existing codebase
- 3. Some API terminology • API Consumer: code that uses API • API: the interface • API Implementer: code that implements API API Consumer API API Implementer Data Access Object JDBC Database Driver
- 4. We are using a lot of API Bazillion Open Source Web Framework API’s Spring: 27 API’s Java EE: 37 API’s Java SE: 45 API’s Enterprise Service API’s Public Service API’s Cloud API’s Middleware API’s
- 5. We are building more of them, too • API is key to a succesful module design – Essential for agile teams at scale Customer Front-‐End Warehouse Front-‐End Order Management Shared code
- 6. Distance to API implementation is increasing • API quality increasing important when implementation becomes a black box Same team Different team Open source Binary only Other datacenter
- 7. The API we use shapes our code • Most code we write calls an API • Code that calls an API is shaped to fit the API • Therefore, APIs determine the shape of application code – In some ways, even more impactful than high level design, test driven development or code craftsmanship
- 8. ! http://docs.oracle.com/javaee/1.4/tutorial/examples/jaxp/xslt/samples/ TransformationApp04.java ! public class TransformationApp04 { public static void main(String[] argv) { if (argv.length != 1) { System.err.println("Usage: java TransformationApp filename"); System.exit(1); } ! // Create the sax "parser". AddressBookReader02 saxReader = new AddressBookReader02(); var json_data = JSON.stringify(obj); try { File f = new File(argv[0]); ! ! // Use a Transformer for output TransformerFactory tFactory = TransformerFactory.newInstance(); Transformer transformer = tFactory.newTransformer(); ! // Use the parser as a SAX source for input FileReader fr = new FileReader(f); BufferedReader br = new BufferedReader(fr); InputSource inputSource = new InputSource(fr); SAXSource source = new SAXSource(saxReader, inputSource); StreamResult result = new StreamResult(System.out); transformer.transform(source, result); } catch (TransformerConfigurationException tce) { // Error generated by the parser System.out.println("n** Transformer Factory error"); System.out.println(" " + tce.getMessage()); !
- 9. What makes a better API
- 10. API Quality: Value • Value = benefits -‐ costs • Benefits – Features – Data – ... • Costs – – – – License/pay per use Performance/footprint Security …
- 11. API Quality: Usability • API Design == Human Interface design – Although API is for machine/machine interaction, APIs need to be understood by programmers to write the code – Programmers are humans API is not just about capability and structural design, but also about human understanding
- 12. A simple model for API Usability Generic usability model by Ben Shneiderman: Learnability: How easy is it to accomplish basic tasks the first time? Efficiency: Once users learned the design, how quickly can they perform tasks? Memorability: When users return after a while, how easily can they re-‐establish proficiency? Errors: How many errors do users make, how severe are these errors, and how easily can they recover from the errors? Satisfaction: How pleasant is it to use the design?
- 13. API Quality: stability Able to enhance/grow implementation without breaking existing consumer code Google AppEngine release notes: Version 1.7.5 -‐ February 13, 2013 The Conversion API, which was decommissioned last release, has been removed from the SDK. In a future release, the API will be removed from the runtime and applications that attempt to use it may stop working. Applications in production that import the library should be fixed as soon as possible. Version 1.8.4 -‐ September 9, 2013 The Conversion API, a decommissioned feature, has been removed from the SDK. In the next release, the API will be removed from the runtime and any attempt to import the API will raise an exception. Version 1.8.5 -‐ September 25, 2013 The Conversion API, a decommissioned feature, has been removed from the runtime. Applications in production that import the API should be fixed as soon as possible.
- 14. API Quality: A hierarchy of needs Stability only matters when API is valuable and usable Stable Usable Valuable
- 16. API Design: start with examples • Examples most important in API documentation – Concrete use case, usability check • Make examples exemplary – Example code will be copy-‐pasted • Create a cheat sheet – Improves learnability – Shows design issues
- 17. API Design: multiple perspectives Names, Completeness, Grouping UML: public class Document { ! ! private List<Page> pages = new ArrayList<>(); Impl: Consumer: public Page addPage() { Page page = new Page(); pages.add(page); page.setPageNumber(pages.size()); return page; } public void report() {...} } Page page = document.addPage(); page.setContents("Once upon a time..."); Can it be built? Is it usable?
- 18. API practice: Keep it simple • Try to stick to just methods and constructors – Factories, Delegates, etc. not always necessary ! • “When in doubt leave it out” – Less classes, methods – Less parameters, return values Josh Bloch, Java API guru
- 19. API practice: avoid verbose constructs • Constructs that create verbose consumer code – Extending class/implementing interface – Checked exception – Required casting – Required generic type – Required if, for, while, try/finally – Required synchronization/locking – Hard coded parameter value
- 20. Example: doing some loggin’ • Demo: different styles of logging API
- 21. Why Lambdas are so much better than inner classes • Inner classes, or extending existing classes often needed – Resource handling – Looping/visiting collections – Event handling • Lambdas provide a much more usable construct – Shorter, safer, better footprint/performance
- 22. Example: Lambda benefits • Demo: Netbeans example
- 23. API practice: fail fast, fail hard • Fail immediately on wrong input • Limit the use of null as valid input/output public void save(String filename) { if (filename == null) { return; // bad api: error is ignored! } ... // save happens here } Better public void save(String filename) { Objects.requireNonNull(filename); // Throws NPE immediately ... // save happens here }
- 24. API Tool: checking for null • Tool: FindBugs, a static code analyzer – Reports errors at compile-‐time • Annotations for Software Defect Detection (JSR 305: Dormant) – @Nonnull: may never be null – @CheckForNull: should always be checked before dereferenced – @Nullable: caller decides if null check is needed • Java 8 will add more annotation options for tools
- 25. FindBugs demo in Eclipse
- 26. Finding API problems in your code • People – Team knowledge – Policy, “best practices”, conventions – Elaborate explanation, “hard to do” – Defect lists/exceptions/stack traces • Tools – Finding most used API: Dependency Structure Matrix (DSM)
- 27. How a Dependency Structure Matrix works Classes/Packages Document Document 2 TextBlock -‐ Page Page TextBlock -‐ 10 # of direct dependencies from Document to Page -‐
- 29. API design cheat sheet API matters: Reuse 3rd party Modular design Distance to impl. A Better API is: 1. Valuable 2. Usable 3. Stable API usability: • Learnability • Efficiency • Memorability • Error rate • Satisfaction API Design Perspectives: UML: names, completeness, grouping Implementation: can it be built API usage: how usable is it Examples First JSR 305/FindBugs: @Nonnull: may never be null @CheckForNull: always check @Nullable: caller decides null check DSM: finding most used API Document Document 2 TextBlock -‐ Page Page TextBlock -‐ 10 @PeterHendriks80, +PeterHendriks -‐ API Design practices: When in doubt leave it out Limit API consumer code to a minimum • Extending class/interface • Checked Exception • Required casting • Required Generic Type • Hard coded parameter value • Required if, for, while, try • Required synchronization/locking ! Be predictable and obvious • Methods calleable in any order • Constructor should only construct • Don’t have surprising side effects • Limit null as input/output • Fail fast, fail hard Eval!