Hold on 20th Sep. 2016 at the "Write the Docs"-conference at Prague

1. Talk at „Write the Docs“
Prague, 20th September 2016
Jan ChrisAan Krause
Using Meaningful
Names to Improve
API-Documentation

2. ©iteratec
Wri$ng useful API-Documenta$on is difficult ...
How to migitate obstacles?
› Include good examples
› Be complete
› Support many complex usage scenarios
› Be conveniently organized
› Include relevant design elements
MarAn P. Robillard: What Makes APIs Hard to Learn? Answers from Developers; In: IEEE SoRware, Vol. 26, No. 6; 2009
2016-09-20 | „Write the Docs“
2

3. ©iteratec ©iteratec ©iteratec
Improving Completeness of API-Documenta$on
An Example from the Java 8 Mail API
public abstract class Transport extends Service {
public void send(Message msg) throws MessagingExcepAon {
// ...
}
}
/**
*
* @param msg
* @throws MessagingExcepAon
*
*/
Addressee(s)?
Message-
Format?
Via which
Server?
Excep$onal
States?
Sends a message.
2016-09-20 | „Write the Docs“
3

4. ©iteratec
Names allow Verifica$on
Are these Objects Volkswagen Type 2 T3-Busses?
==
Matches
Paaern?
Object A
Object B
2016-09-20 | „Write the Docs“
4

5. ©iteratec
Match the API-DocumentaAon
against the chosen paaern
3
Applying Documenta$on PaWerns
SubmiXng Opera$on
Verbs: to send, to submit, to noAfy
@DESTINATION Where the MESSAGE is recieved
@MESSAGE What is transferred
@FORMAT The structure of the transferred MESSAGE
@INSTRUMENT The infrastructure used to transfer the
MESSAGE
› public void send(Message msg)
› public void submit(Message msg)
› public void noAfy(Message msg)
› [...]
Choose the Verb
for the operaAon
1
Find the best matching
documentaAon
paaern
2
2016-09-20 | „Write the Docs“
5

6. ©iteratec
Using Names to Detect Gaps in API-Documenta$on
Applying Documenta$on PaWerns (I)
/**
* Sends a message.
*
* @des$na$on The message will be sent to all recipient addresses specified in the message (as
* returned from the Message method getAllRecipients), using message transports appropriate
* to each address. The send method calls the saveChanges method on the message before sending it.
*
* @instrument Note that send is a staAc method that creates and manages its own connecAon.
* Any connecAon associated with any Transport instance used to invoke this method is ignored and
* not used. This method should only be invoked using the form Transport.send(msg), and should never
* be invoked using an instance variable.
* @param msg [MESSAGE]
* @throws MessagingExcepAon
* [...]
2016-09-20 | „Write the Docs“
6

7. ©iteratec
Using Names to Detect Gaps in API-Documenta$on
Applying Documenta$on PaWerns (II)
* @des$na$on [ERROR] In typical usage, a SendFailedExcepAon reflects an error detected by the server.
* The details of the SendFailedExcepAon will usually contain the error message from the server (such as an
* SMTP error message). An address may be detected as invalid for a variety of reasons - the address may
* not exist, the address may have invalid syntax, the address may have exceeded its quota, etc. If any of
* the recipient addresses is detected to be invalid by the Transport during message submission, a
* SendFailedExcepAon is thrown. Clients can get more detail about the failure by examining the excepAon.
* Whether or not the message is sAll sent successfully to any valid addresses depends on the Transport
* implementaAon. See SendFailedExcepAon for more details.
*
* @instrument [ERROR] Note also that success does not imply that the message was delivered to the
* ulAmate recipient, as failures may occur in later stages of delivery. Once a Transport accepts a message
* for delivery to a recipient, failures that occur later should be reported to the user via another
* mechanism, such as returning the undeliverable message.
**/
2016-09-20 | „Write the Docs“
7

8. ©iteratec
The Documenta$on PaWerns I found so far ...
2016-09-20 | „Write the Docs“
8
Types of Opera$ons:
Checking Deriving Merging Parsing DeposiAng
Reading DeleAng
ConverAng Searching
Submitng
IniiaAng Replacing
Traversing ….
Describing
Resetng
CompuAng
ConnecAng
CreaAng
DuplicaAng
Logging

9. ©iteratec
I share them here:
github.com/jankrause/wtd-2016

10. ©iteratec
Advantages of this Approach:
› IdenAfy characterisAcs of an operaAon, which are invisible on its signature
(e.g. resources, algorithms or formulas)
› Derive excepAonal cases
› Improve understandability of the API through usage of meaningful verbs

11. www.iteratec.de
Dr. Jan Christian Krause
Mail: jan-christian.krause@iteratec.de
Twitter: @idocit
Github: github.com/jankrause