Writing usable APIs in practice

Transcription

1 Writing usable APIs in practice NDC Oslo linkedin: Asprotunity Ltd

2 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., cdesouza/pub/p390-desouza.pdf

3 Example: java.io package (Java 7) Interfaces: Closeable, DataInput, DataOutput, Externalizable, FileFilter, FilenameFilter, Flushable, ObjectInput, ObjectInputValidation, ObjectOutput, ObjectStreamConstants, Serializable Classes: 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 Exceptions: CharConversionException, EOFException, FileNotFoundException, InterruptedIOException, InvalidClassException, InvalidObjectException, IOException, NotActiveException, NotSerializableException, ObjectStreamException, OptionalDataException, StreamCorruptedException, SyncFailedException, UnsupportedEncodingException, UTFDataFormatException, WriteAbortedException Errors: IOError

4 Usability Efficiency Effectiveness Error prevention Ease of learning

5 Giovanni s usability equation u = O(1/b) u = usability b = brain power necessary to achieve your goals

6 The equation is... Made up Totally arbitrary

7 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

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

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

10 Any non trivial software application involves writing one or more APIs

11 When we talk about good code we always mean usable code as well

12 Some usability concepts

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

14 import java.io.bufferedreader; import java.io.file; import java.io.filereader; 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();

15 import java.nio.file.path; import java.nio.filesystems; import java.nio.charset.charset; 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

16 import java.io.file; import java.util.scanner; File file = new File("filename"); try { Scanner scanner = new Scanner(file); while (scanner.hasnextline()) { String line = scanner.nextline(); processline(line); scanner.close(); catch (FileNotFoundException e) { e.printstacktrace();

17 with open("filename") as infile: for line in infile.readlines(): processline(line)

18 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. The extent to which a developer must understand the underlying implementation details of an API 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,

19 import java.io.bufferedreader; import java.io.file; import java.io.filereader; 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

20 import java.nio.file.path; import java.nio.filesystems; import java.nio.charset.charset; 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

21 import java.io.file; import java.util.scanner; File file = new File("filename"); try { Scanner scanner = new Scanner(file); while (scanner.hasnextline()) { String line = scanner.nextline(); processline(line); scanner.close(); catch (FileNotFoundException e) { e.printstacktrace(); Abstraction level Working framework Progressive evaluation Penetrability Consistency

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

23 Some techniques

24 None of the ideas presented here are new; they are just forgotten from time to time. Alan J. Perlis, 1966 Turing Award Lecture.

25 User s perspective Naming Explicit context Error reporting Incremental design

26 User s perspective Naming Explicit context Error reporting Incremental design

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

28 Use language constructs to make intent clear

29 maketv(true, false); From: API Design Matters, Michi Henning, id=

30 void maketv(bool iscolor, bool iscrt); From: API Design Matters, Michi Henning, id=

31 enum ColorType { Color, BlackAndWhite enum ScreenType { CRT, FlatScreen ; void maketv(colortype col, ScreenType st); From: API Design Matters, Michi Henning, id=

32 maketv(color, FlatScreen); From: API Design Matters, Michi Henning, id=

33 Give control to the caller

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

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

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

37 TDD helps with Abstraction level. It helps to limit the number of abstractions in mainline scenarios Working framework. It helps in keeping it smaller Progressive evaluation. The tests themselves are written in a progressive way Penetrability. It provides examples on how the various components interact with each other Consistency. It is maintained by refactoring the code

38 Back to the first example: potential test with TDD List<String> expectedlines = ; File file = new File( testfile )); assertequals(file.readlines(), expectedlines);

39 More likely outcome File file = new File( filename )); try { for (String line : file.readlines()) { processline(line); finally { file.close()

40 Less likely outcome 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();

41 User s perspective Naming Explicit context Error reporting Incremental design

42 Naming Reserve the simplest and most intuitive names for the entities used in the most common scenarios Pick one word per concept Use easy to remember conventions Don t be cute!

43 What not to do (1/2) java.io.objectstreamconstants Constants written into the Object Serialization Stream

44

45 User s perspective Naming Explicit context Error reporting Incremental design

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

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

48 Runtime context Initialization (and finalization) steps Preconditions for calling methods (or functions) or instantiating classes Assumptions about global application state

49 Global state Difficult to use in a concurrent environment Can make test setup extremely hard Can make penetrability really hard by hiding dependencies

50 User s perspective Naming Explicit context Error reporting Incremental design

51 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

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

53 Error management and reporting need careful design from the very beginning

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

55 User s perspective Naming Explicit context Error reporting Incremental design

56 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

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

58 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

59 Surprising study results

60 Factory pattern A user study comparing the usability of the factory pattern and constructors in API designs found highly significant results indicating that factories are detrimental to API usability in several varied situations. The results showed that users require significantly more time (p = 0.005) to construct an object with a factory than with a constructor while performing both context-sensitive and context free tasks From: The Factory Pattern in API Design: A Usability Evaluation

61 Constructors It was hypothesized that required parameters would create more usable and self documenting APIs by guiding programmers toward the correct use of objects and preventing errors. However, in the study, it was found that, contrary to expectations, programmers strongly preferred and were more effective with APIs that did not require constructor parameters. Participants behavior was analyzed using the cognitive dimensions framework, and revealing that required constructor parameters interfere with common learning strategies, causing undesirable premature commitment. From: Usability Implications of Requiring Parameters in Objects Constructors

62 Links Sometimes You Need to See Through Walls A Field Study of Application Programming Interfaces, Cleidson R. B. de Souza et al., Measuring API Usability, Steven Clarke, API Design Matters, Michi Henning, How to Design a Good API and Why it Matters, Joshua Bloch, What Makes APIs Difficult to Use?, Minhaz Fahim Zibran, Usability Implications of Requiring Parameters in Objects Constructors, Jeffrey Stylos and Steven Clarke, The Factory Pattern in API Design: A Usability Evaluation, Brian Ellis, Jeffrey Stylos, and Brad Myers,

63 Books ptg From the Library of Giovanni Asproni