15-214 Agenda Principles of Software Construction: Objects, - PowerPoint PPT Presentation

15-214 Agenda Principles of Software Construction: Objects, Design, and Concurrency • Introduction to APIs: Application (Part 5: Large-Scale Reuse) Programming Interfaces • An API design process • Key design principle: Information hiding Principles of API Design • Concrete advice for user-centered design Christian Kästner Charlie Garrod Closely based on How To Design A Good School of Computer Science API and Why It Matters by Josh Bloch 2 15-214 15-214 15-214 1 2 3 API: Application Programming Agenda Learning goals Interface • Introduction to APIs: Application Programming • Understand and be able to discuss the similarities • An API defines the boundary between and differences between API design and regular Interfaces components/modules in a programmatic software design • An API design process system – Relationship between libraries, frameworks and API • Key design principle: Information hiding design – Information hiding as a key design principle • Concrete advice for user-centered design • Acknowledge, and plan for failures as a • Based heavily on "How to Design a Good API and fundamental limitation on a design process Why it Matters by Josh Bloch" • Given a problem domain with use cases, be able – If you have "Java" in your resume you to plan a coherent design process for an API for should own Effective Java , our optional those use cases, e.g., "Rule of Threes" course textbook. 15-214 15-214 15-214 4 5 6 1

15-214 API: Application Programming API: Application Programming API: Application Programming Interface Interface Interface • An API defines the boundary between • An API defines the boundary between • An API defines the boundary between components/modules in a programmatic components/modules in a programmatic components/modules in a programmatic system system system 15-214 15-214 15-214 7 8 9 Libraries and frameworks both define APIs are forever APIs are forever APIs API public MyWidget extends JContainer { ublic MyWidget(int param) { / setup internals, without rendering } Library / render component on first view and Your JDT Plugin resizing protected void paintComponent(Graphics g) { // draw a red box on his component Dimension d = getSize(); g.setColor(Color.red); g.drawRect(0, 0, d.getWidth(), colleague (IBM) d.getHeight()); } } Your Eclipse your code code (IBM) Another CDT Plugin colleague (IBM) API public MyWidget extends JContainer { Somebody UML Plugin ublic MyWidget(int param) { / setup internals, without rendering Somebody Somebody } Framework / render component on first view and Somebody Somebody resizing on the web (third party) protected void Somebody Somebody paintComponent(Graphics g) { // draw a red box on his on the web on the web component Dimension d = getSize(); Somebody Somebody g.setColor(Color.red); on the web on the web g.drawRect(0, 0, d.getWidth(), d.getHeight()); } Somebody Somebody on the web on the web } Somebody Somebody on the web on the web your code Somebody third party on the web on the web on the web on the web on the web plugin 11 12 15-214 15-214 15-214 10 11 12 2

15-214 Evolutionary problems: Public (used) APIs are everywhere Motivation to create a public API APIs are forever • Good APIs are a great asset • "One chance to get it right" • Frameworks – Distributed development among many teams • Can add features to library • Libraries • Incremental, non-linear software development • Cannot remove method from library • Any code that is reused really • Facilitates communication – …may turn slowly into a library – Long-term buy-in from clients & customers • Cannot change contract in library • Poor APIs are a great liability • Cannot change plugin interface of framework – Lost productivity from your software developers • Deprecation of APIs as weak workaround – Lack of buy-in from clients & customers awt.Component, – Wasted customer support resources deprecated since Java 1.1 still included in 7.0 14 15-214 15-214 15-214 13 14 15 Good and bad APIs An API design process Case Study: Java Date and Calendars • Define the scope of the API • Lots of reuse • Lost productivity, inefficient reuse – Collect use-case stories, define requirements – including from yourself – Be skeptical • Lots of users/customers • Maintenance and • Distinguish true requirements from so-called solutions customer support • User buy-in and lock-in • "When in doubt, leave it out." liability • Draft a specification, gather feedback, revise, and repeat – Keep it simple, short • Code early, code often – Write client code before you implement the API 16 18 15-214 15-214 15-214 16 17 18 3

15-214 Plan with Use Cases Respect the rule of three Contracts and Documentation • APIs should be self-documenting • Think about how the API might be used? • Via Will Tracz (via Josh Bloch), Confessions of a – Good names drive good design – e.g., get the current time, compute the difference Used Program Salesman : • Document religiously anyway between two times, get the current time in Tokyo, – "If you write one, it probably won't support – All public classes get next week's date using a Maya calendar, … another." – All public methods • What tasks should it accomplish? – "If you write two, it will support more with – All public fields – All method parameters difficulty." • Should all the tasks be supported? – Explicitly write behavioral specifications – "If you write three, it will work fine." – If in doubt, leave it out! • Documentation is integral to the design and development process • How would you solve the tasks with the API? 19 15-214 15-214 15-214 19 20 21 Key design principle: Information Contracts and Documentation hiding • APIs should be self-documenting • "When in doubt, leave it out." public class Point { – Good names drive good design public double x; • Document religiously anyway public double y; – All public classes } – All public methods vs. – All public fields public class Point { – All method parameters private double x; – Explicitly write behavioral specifications private double y; • Documentation is integral to the design and public double getX () { /* … */ } development process public double getY () { /* … */ } • Do not document implementation details } 15-214 15-214 15-214 22 23 24 4

15-214 Key design principle: Information Applying Information Hiding: hiding (2) Fields vs Getter/Setter Functions • Minimize the accessibility of classes, fields, public class Point { public double x; public class Rectangle { and methods public double y; public Rectangle(Point e, Point f) … – "You can add features, but never remove or } } change the behavioral contract for an existing vs. vs. feature" public class Point { public class Rectangle { private double x; public Rectangle(PolarPoint e, PolarPoint f) … } private double y; public double getX () { /* … */ } public double getY () { /* … */ } } 15-214 15-214 15-214 25 26 27 Applying Information hiding: Applying Information Hiding: Applying Information hiding: Factories Interface vs. Class Types Hide Information Details • Subtle leaks of implementation details • Consider implementing a factory method public class Rectangle { through instead of a constructor public Rectangle(Point e, Point f) … – Documentation • Factory methods provide additional flexibility } – Implementation-specific return types vs. – Can be overridden – Implementation-specific exceptions public class Rectangle { – Can return instance of any subtype; hides dynamic – Output formats public Rectangle(PolarPoint e, PolarPoint f) … type of object } – implements Serializable – Can have a descriptive method name • Lack of documentation -> Implementation becomes specification – > no hiding 15-214 15-214 15-214 28 29 30 5

15-214 Apply principles of user-centered Minimize conceptual weight design • Other programmers are your users public class Thread implements Runnable { • Conceptual weight: How many concepts must // Tests whether current thread has been interrupted. • e.g., "Principles of Universal Design" a programmer learn to use your API? // Clears the interrupted status of current thread. – Equitable use – APIs should have a "high power-to-weight ratio" public static boolean interrupted(); } – Flexibility in use • See java.util.* , – Simple and intuitive use java.util.Collections – Perceptible information – Tolerance for error – Low physical effort – Size and space for approach and use 15-214 15-214 15-214 31 32 33 Good names drive good design Good names drive good design (2) • Do what you say you do: – get_x() vs getX() • Follow language- and platform-dependent – "Don't violate the Principle of Least Astonishment" – Timer vs timer conventions public class Thread implements Runnable { – isEnabled() vs. enabled() – Typographical: // Tests whether current thread has been interrupted. – computeX() vs. generateX()? • get_x() vs. getX() // Clears the interrupted status of current thread. • timer vs. Timer, HTTPServlet vs HttpServlet – deleteX() vs. removeX()? public static boolean interrupted(); • edu.cmu.cs.cs214 } – Grammatical: • Nouns for classes • Nouns or adjectives for interfaces 15-214 15-214 15-214 34 35 36 6