Writing usable APIs in practice

Transcription

1 Writing usable APIs in practice SyncConf 2013 Giovanni

2 Summary API definition Two assumptions Why bother with usability Some usability concepts Some techniques to improve usability

3 API Any well-defined interface that defines the service that one component, module, or application provides to other software elements From: Sometimes You Need to See Through Walls A Field Study of Application Programming Interfaces, Cleidson R. B. de Souza et al., pub/p390-desouza.pdf

4 Submit a bug or feature Package java.io Provides for system input and output through data streams, serialization and the file system. See: Description Interface Summary Interface Closeable DataInput DataOutput Externalizable FileFilter FilenameFilter Flushable ObjectInput ObjectInputValidation ObjectOutput ObjectStreamConstants Serializable Description A Closeable is a source or destination of data that can be closed. The DataInput interface provides for reading bytes from a binary stream and reconstructing from them data in any of the Java primitive types. The DataOutput interface provides for converting data from any of the Java primitive types to a series of bytes and writing these bytes to a binary stream. Only the identity of the class of an Externalizable instance is written in the serialization stream and it is the responsibility of the class to save and restore the contents of its instances. A filter for abstract pathnames. Instances of classes that implement this interface are used to filter filenames. A Flushable is a destination of data that can be flushed. ObjectInput extends the DataInput interface to include the reading of objects. Callback interface to allow validation of objects within a graph. ObjectOutput extends the DataOutput interface to include writing of objects. Constants written into the Object Serialization Stream. Serializability of a class is enabled by the class implementing the java.io.serializable interface. Class Summary Class BufferedInputStream BufferedOutputStream BufferedReader BufferedWriter ByteArrayInputStream ByteArrayOutputStream CharArrayReader CharArrayWriter Console DataInputStream DataOutputStream File FileDescriptor FileInputStream FileOutputStream FilePermission FileReader FileWriter FilterInputStream FilterOutputStream FilterReader FilterWriter InputStream InputStreamReader LineNumberInputStream LineNumberReader ObjectInputStream ObjectInputStream.GetField ObjectOutputStream ObjectOutputStream.PutField ObjectStreamClass ObjectStreamField OutputStream OutputStreamWriter PipedInputStream PipedOutputStream PipedReader PipedWriter PrintStream PrintWriter PushbackInputStream PushbackReader RandomAccessFile Reader SequenceInputStream SerializablePermission StreamTokenizer StringBufferInputStream StringReader StringWriter Writer Description A BufferedInputStream adds functionality to another input stream-namely, the ability to buffer the input and to support the mark and reset methods. The class implements a buffered output stream. Reads text from a character-input stream, buffering characters so as to provide for the efficient reading of characters, arrays, and lines. Writes text to a character-output stream, buffering characters so as to provide for the efficient writing of single characters, arrays, and strings. A ByteArrayInputStream contains an internal buffer that contains bytes that may be read from the stream. This class implements an output stream in which the data is written into a byte array. This class implements a character buffer that can be used as a character-input stream. This class implements a character buffer that can be used as an Writer. Methods to access the character-based console device, if any, associated with the current Java virtual machine. A data input stream lets an application read primitive Java data types from an underlying input stream in a machine-independent way. A data output stream lets an application write primitive Java data types to an output stream in a portable way. An abstract representation of file and directory pathnames. Instances of the file descriptor class serve as an opaque handle to the underlying machine-specific structure representing an open file, an open socket, or another source or sink of bytes. A FileInputStream obtains input bytes from a file in a file system. A file output stream is an output stream for writing data to a File or to a FileDescriptor. This class represents access to a file or directory. Convenience class for reading character files. Convenience class for writing character files. A FilterInputStream contains some other input stream, which it uses as its basic source of data, possibly transforming the data along the way or providing additional functionality. This class is the superclass of all classes that filter output streams. Abstract class for reading filtered character streams. Abstract class for writing filtered character streams. This abstract class is the superclass of all classes representing an input stream of bytes. An InputStreamReader is a bridge from byte streams to character streams: It reads bytes and decodes them into characters using a specified charset. Deprecated This class incorrectly assumes that bytes adequately represent characters. A buffered character-input stream that keeps track of line numbers. An ObjectInputStream deserializes primitive data and objects previously written using an ObjectOutputStream. Provide access to the persistent fields read from the input stream. An ObjectOutputStream writes primitive data types and graphs of Java objects to an OutputStream. Provide programmatic access to the persistent fields to be written to ObjectOutput. Serialization's descriptor for classes. A description of a Serializable field from a Serializable class. This abstract class is the superclass of all classes representing an output stream of bytes. An OutputStreamWriter is a bridge from character streams to byte streams: Characters written to it are encoded into bytes using a specified charset. A piped input stream should be connected to a piped output stream; the piped input stream then provides whatever data bytes are written to the piped output stream. A piped output stream can be connected to a piped input stream to create a communications pipe. Piped character-input streams. Piped character-output streams. A PrintStream adds functionality to another output stream, namely the ability to print representations of various data values conveniently. Prints formatted representations of objects to a text-output stream. A PushbackInputStream adds functionality to another input stream, namely the ability to "push back" or "unread" one byte. A character-stream reader that allows characters to be pushed back into the stream. Instances of this class support both reading and writing to a random access file. Abstract class for reading character streams. A SequenceInputStream represents the logical concatenation of other input streams. This class is for Serializable permissions. The StreamTokenizer class takes an input stream and parses it into "tokens", allowing the tokens to be read one at a time. Deprecated This class does not properly convert characters into bytes. A character stream whose source is a string. A character stream that collects its output in a string buffer, which can then be used to construct a string. Abstract class for writing to character streams. Exception Summary Exception CharConversionException EOFException FileNotFoundException InterruptedIOException InvalidClassException InvalidObjectException IOException NotActiveException NotSerializableException ObjectStreamException OptionalDataException StreamCorruptedException SyncFailedException UnsupportedEncodingException UTFDataFormatException WriteAbortedException Description Base class for character conversion exceptions. Signals that an end of file or end of stream has been reached unexpectedly during input. Signals that an attempt to open the file denoted by a specified pathname has failed. Signals that an I/O operation has been interrupted. Thrown when the Serialization runtime detects one of the following problems with a Class. Indicates that one or more deserialized objects failed validation tests. Signals that an I/O exception of some sort has occurred. Thrown when serialization or deserialization is not active. Thrown when an instance is required to have a Serializable interface. Superclass of all exceptions specific to Object Stream classes. Exception indicating the failure of an object read operation due to unread primitive data, or the end of data belonging to a serialized object in the stream. Thrown when control information that was read from an object stream violates internal consistency checks. Signals that a sync operation has failed. The Character Encoding is not supported. Signals that a malformed string in modified UTF-8 format has been read in a data input stream or by any class that implements the data input interface. Signals that one of the ObjectStreamExceptions was thrown during a write operation. Error Summary Error IOError Description Thrown when a serious I/O error has occurred. Package java.io Description Provides for system input and output through data streams, serialization and the file system. Unless otherwise noted, passing a null argument to a constructor or method in any class or interface in this package will cause a NullPointerException to be thrown. Package Specification Java Object Serialization Specification Related Documentation For overviews, tutorials, examples, guides, and tool documentation, please see: Serialization Enhancements Since: JDK1.0 Overview Package Class Use Tree Deprecated Index Help Java Platform Standard Ed. 7 Prev Package Next Package Frames No Frames All Classes

5 Public and private APIs Public APIs Given to third parties Private APIs For internal use

6 First assumption Any non trivial software application involves writing one or more APIs

7 Second assumption When we talk about good code we always mean usable code as well

8 Why bother (company s perspective) APIs can be among a company's greatest assets Can also be among company's greatest liabilities Adapted from: How to Design a Good API and Why it Matters, Joshua Bloch, keynote.pdf

9 Why bother (programmer s perspective) Fewer bugs to take care of Code of higher quality More productivity

10 Affordances An affordance is a quality of an object, or an environment, that allows an individual to perform an action. From:

11 Affordances: processing file line by line (Java 6) BufferedReader reader; try { reader = new BufferedReader(new FileReader( filename )); while (true) { String line = reader.readline(); if (line == null) { break; processline(line); catch (Exception exc) { // Do something here... finally { if (reader!= null) { reader.close();

12 Affordances that are easier to see (Java 7) try { Path filepath = FileSystems.getDefault().getPath("filename"); Charset charset = Charset.defaultCharset(); for (String line : Files.readAllLines(filePath, charset)) { processline(line); catch (IOException e) { // Do something here

13 And even easier (Python 3) with open("filename") as infile: for line in infile.readlines(): processline(line)

14 Some cognitive dimensions Abstraction level. The minimum and maximum levels of abstraction exposed by the API Working framework. The size of the conceptual chunk (developer working set) needed to work effectively Progressive evaluation. To what extent partially completed code can be executed to obtain feedback on code behaviour Penetrability. How the API facilitates exploration, analysis, and understanding of its components Consistency. How much of the rest of an API can be inferred once part of it is learned Adapted from: Measuring API Usability, Steven Clarke,

15 BufferedReader reader; try { reader = new BufferedReader(new FileReader( filename )); while (true) { String line = reader.readline(); if (line == null) { break; processline(line); catch (Exception exc) { // Do something here... finally { if (reader!= null) { reader.close(); Abstraction level. Working framework. Progressive evaluation. Penetrability. Consistency.

16 try { Path filepath = FileSystems.getDefault().getPath("filename"); Charset charset = Charset.defaultCharset(); for (String line : Files.readAllLines(filePath, charset)) { processline(line); catch (IOException e) { // Do something here Abstraction level. Working framework. Progressive evaluation. Penetrability. Consistency.

17 with open("filename") as infile: for line in infile.readlines(): processline(line) Abstraction level. Working framework. Progressive evaluation. Penetrability. Consistency.

18 Make Interfaces Easy to Use Correctly and Hard to Use Incorrectly Scott Meyers, 97 Things Every Programmer Should Know

19 Some techniques User s perspective Naming Give control to the caller Explicit context Error reporting Logging as a feature Incremental design

20 User s perspective Naming Give control to the caller Explicit context Error reporting Logging as a feature Incremental design

21 Ask, What Would the User Do? (You Are Not the User) Giles Colborne, 97 Things Every Programmer Should Know

22 Golden Rule of API Design 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 follow this rule, you learn firsthand the hurdles that your users will have to overcome when they try to test their code independently. Michael Feathers, 97 Things Every Programmer Should Know

23 TDD It puts you in the shoes of an user If writing a test is painful, the design may be wrong Tests will provide up to date documentation and examples of use

24 TDD helps with Abstraction level. It helps to limit the number of abstractions in mainline scenarios Working framework Progressive evaluation Penetrability. It provides examples on how the various components interact with each other Consistency. It is maintained by refactoring the code Adapted from: Measuring API Usability, Steven Clarke,

25 File file = new File( filename )); try { for (String line : file.readlines()) { processline(line); finally { file.close()

26 BufferedReader reader; try { reader = new BufferedReader(new FileReader( filename )); while (true) { String line = reader.readline(); if (line == null) { break; processline(line); catch (Exception exc) { // Do something here... finally { if (reader!= null) { reader.close();

27 User s perspective Naming Give control to the caller Explicit context Error reporting Logging as a feature Incremental design

28 Reserve the simplest and most intuitive names names for the entities used in the most common scenarios Pick one word per concept Don t be cute!

29 User s perspective Naming Give control to the caller Explicit context Error reporting Logging as a feature Incremental design

30 What s wrong with these? public interface Startable { Startable start() throws AlreadyStartedException; public interface Stoppable { Stoppable stop() throws AlreadyStoppedException;

31 A better alternative public interface Service { void start() throws AlreadyStartedException; void stop() throws AlreadyStoppedException; boolean isstarted();

32 User s perspective Naming Give control to the caller Explicit context Error reporting Logging as a feature Incremental design

33 Explicit context Assumptions about the external environment There are two kinds of context we are interested in Deployment context Runtime context

34 Deployment context Dependencies on other APIs Assumptions on deployment paths User permissions etc.

35 Runtime context Preconditions for calling methods (or functions) or instantiating classes Initialisation (and finalisation) steps etc.

36 Global state Difficult to use in a concurrent environment Can make test setup extremely hard Can make functionality difficult to use by hiding dependencies

37 User s perspective Naming Give control to the caller Explicit context Error reporting Logging as a feature Incremental design

38 Error reporting Error reporting code is important for usability Users need to know How errors are reported What is reported when What they can do about them

39 Error recovery Make recovery easy to do Error codes Exception classes A mix of the above Text messages are usually not good enough

40 What is an error at one level......may not be an error at another one

41 User s perspective Naming Give control to the caller Explicit context Error reporting Logging as a feature Incremental design

42 Two types of logging Support logging (errors and info) is part of the user interface of the application. These messages are intended to be tracked by support staff and operators to monitor the running system Diagnostic logging (debug and trace) is infrastructure for programmers. Not for production Adapted from: Growing Object Oriented Code Driven by Tests, Steve Freeman and Nat Pryce, Addison Wesley

43 Location location = tracker.getcurrentlocation(); for (Filter filter : filters) { filter.selectfor(location); if (logger.isinfoenabled()) { logger.info("filter " + filter.getname() + ", " + filter.getdate() + " selected for " + location.getname() + ", is current: " + tracker.iscurrent(location)); From: Growing Object Oriented Code Driven by Tests, Steve Freeman and Nat Pryce, Addison Wesley

44 Location location = tracker.getcurrentlocation(); for (Filter filter : filters) { filter.selectfor(location); support.notifyfiltering(tracker, location, filter); From: Growing Object Oriented Code Driven by Tests, Steve Freeman and Nat Pryce, Addison Wesley

45 Give the programmer a choice It should be possible to turn logging on and off When on, give programmers a chance to use logging on their own terms

46 User s perspective Naming Give control to the caller Explicit context Error reporting Logging as a feature Incremental design

47 Conceptual integrity I will contend that conceptual integrity is the most important consideration in system design. It is better to have a system omit certain anomalous features and improvements, but to reflect one set of design ideas, than to have one that contains many good but independent and uncoordinated ideas. Fred Brooks, The Mythical Man Month

48 Start specific and small Start with the 80% case first It is easier to remove constraints rather than to add them later YAGNI

49 A caveat Public APIs are more difficult to refactor. In fact, some errors may actually become features Techniques to refactor them usually involve some form of deprecation and versioning

50 User s perspective Naming Give control to the caller Explicit context Error reporting Logging as a feature Incremental design

51 Links Sometimes You Need to See Through Walls A Field Study of Application Programming Interfaces, Cleidson R. B. de Souza et al., cdesouza/pub/p390-desouza.pdf Measuring API Usability, Steven Clarke, How to Design a Good API and Why it Matters, Joshua Bloch, lcsd05.cs.tamu.edu/slides/keynote.pdf What Makes APIs Difficult to Use?, Minhaz Fahim Zibran, paper.ijcsns.org/07_book/200804/ pdf

52 Books ptg From the Library of Giovanni Asproni