using meaningful names to improve api documentation
TRANSCRIPT
Talkat„WritetheDocs“
Prague,20thSeptember2016JanChrisAanKrause
Using Meaningful Names to Improve API-Documentation
©ite
ratec
Wri$ngusefulAPI-Documenta$onisdifficult...Howtomigitateobstacles?
› Includegoodexamples
› Becomplete
› Supportmanycomplexusagescenarios
› Beconvenientlyorganized› IncluderelevantdesignelementsMarAnP.Robillard:WhatMakesAPIsHardtoLearn?AnswersfromDevelopers;In:IEEESoRware,Vol.26,No.6;2009
2016-09-20|„WritetheDo
cs“
2
©ite
ratec
©ite
ratec
©ite
ratec
ImprovingCompletenessofAPI-Documenta$onAnExamplefromtheJava8MailAPI
publicabstractclassTransportextendsService{publicvoidsend(Messagemsg)throwsMessagingExcepAon{//... }}
/****@parammsg*@throwsMessagingExcepAon**/
Addressee(s)?
Message-Format?
ViawhichServer?
Excep$onalStates?
Sendsamessage.
2016-09-20|„WritetheDo
cs“
3
©ite
ratec
NamesallowVerifica$onAretheseObjectsVolkswagenType2T3-Busses?
==
MatchesPaaern?
ObjectA
ObjectB
2016-09-20|„WritetheDo
cs“
4
©ite
ratec
MatchtheAPI-DocumentaAonagainstthechosenpaaern
3
ApplyingDocumenta$onPaWerns
SubmiXngOpera$on
Verbs: tosend,tosubmit,tonoAfy
@DESTINATION WheretheMESSAGEisrecieved
@MESSAGE Whatistransferred
@FORMAT ThestructureofthetransferredMESSAGE
@INSTRUMENT TheinfrastructureusedtotransfertheMESSAGE
› publicvoidsend(Messagemsg)› publicvoidsubmit(Messagemsg)› publicvoidnoAfy(Messagemsg)› [...]
ChoosetheVerbfortheoperaAon
1FindthebestmatchingdocumentaAonpaaern
2
2016-09-20|„WritetheDo
cs“
5
©ite
ratec
UsingNamestoDetectGapsinAPI-Documenta$onApplyingDocumenta$onPaWerns(I)
/***Sendsamessage.**@des$na$onThemessagewillbesenttoallrecipientaddressesspecifiedinthemessage(as*returnedfromtheMessagemethodgetAllRecipients),usingmessagetransportsappropriate*toeachaddress.ThesendmethodcallsthesaveChangesmethodonthemessagebeforesendingit.**@instrumentNotethatsendisastaAcmethodthatcreatesandmanagesitsownconnecAon.*AnyconnecAonassociatedwithanyTransportinstanceusedtoinvokethismethodisignoredand*notused.ThismethodshouldonlybeinvokedusingtheformTransport.send(msg),andshouldnever*beinvokedusinganinstancevariable.
*@parammsg[MESSAGE]
*@throwsMessagingExcepAon*[...]
2016-09-20|„WritetheDo
cs“
6
©ite
ratec
UsingNamestoDetectGapsinAPI-Documenta$onApplyingDocumenta$onPaWerns(II)
*@des$na$on[ERROR]Intypicalusage,aSendFailedExcepAonreflectsanerrordetectedbytheserver.*ThedetailsoftheSendFailedExcepAonwillusuallycontaintheerrormessagefromtheserver(suchasan*SMTPerrormessage).Anaddressmaybedetectedasinvalidforavarietyofreasons-theaddressmay*notexist,theaddressmayhaveinvalidsyntax,theaddressmayhaveexceededitsquota,etc.Ifanyof*therecipientaddressesisdetectedtobeinvalidbytheTransportduringmessagesubmission,a*SendFailedExcepAonisthrown.ClientscangetmoredetailaboutthefailurebyexaminingtheexcepAon.*WhetherornotthemessageissAllsentsuccessfullytoanyvalidaddressesdependsontheTransport*implementaAon.SeeSendFailedExcepAonformoredetails.**@instrument[ERROR]Notealsothatsuccessdoesnotimplythatthemessagewasdeliveredtothe*ulAmaterecipient,asfailuresmayoccurinlaterstagesofdelivery.OnceaTransportacceptsamessage*fordeliverytoarecipient,failuresthatoccurlatershouldbereportedtotheuserviaanother*mechanism,suchasreturningtheundeliverablemessage.**/
2016-09-20|„WritetheDo
cs“
7
©ite
ratec
TheDocumenta$onPaWernsIfoundsofar...
2016-09-20|„WritetheDo
cs“
8
TypesofOpera$ons:
Checking Deriving Merging Parsing DeposiAng
Reading DeleAngConverAng Searching
Submitng
IniiaAng Replacing
Traversing ….
Describing
Resetng
CompuAng
ConnecAng
CreaAng
DuplicaAng
Logging
©ite
ratec
I share them here: github.com/jankrause/wtd-2016
©ite
ratec
AdvantagesofthisApproach:› IdenAfycharacterisAcsofanoperaAon,whichareinvisibleonitssignature(e.g.resources,algorithmsorformulas)
› DeriveexcepAonalcases› ImproveunderstandabilityoftheAPIthroughusageofmeaningfulverbs
www.iteratec.de
Dr. Jan Christian Krause Mail: [email protected] Twitter: @idocit Github: github.com/jankrause