"You probably should be reading this..." - Getting people to read your JavaDocs with eMoose

Uri Dekel

Eclipse IDE And Languages - Java · Short - 30 minutes  slideshare
Wednesday, 10:30, 30 minutes | Room 209/210

7
·
8
·
9
·
10
·
11
·
12
·
13
·
14
·
15
·
16
·
17
·
18

An unfortunate reality of Java development is that we rarely have the time to thoroughly read the documentation of every method we invoke, or even to read it at all. Most of the time we can safely rely on the signature, as the detailed specifications are consistent with our expectations. In some cases, however, the JavaDocs also convey unexpected “directives”, such as rules that callers must follow or caveats of which they should be aware. If these go unnoticed, the consequences could be severe.

The first part of this talk will present examples of surprisingly hazardous situations from the standard library and suggest practices that documentation authors can follow to help readers notice directives in the text. With standard tools, however, there is no way for these authors to attract callers to read the text in the first place. The second part of this talk will describe how our eMoose framework can help make developers aware of directives in invoked methods. Authors can explicitly tag directives in the JavaDocs and distribute libraries of tags to clients. Our Eclipse plug-in continuously monitors the Java editor and attempts to match all call targets against these tags. If a match is found the call is decorated, offering a cue that the documentation may be worth investigating.

eMoose if freely available from http://emoose.cs.cmu.edu

Uri is a Ph.D. candidate of Software Engineering at Carnegie Mellon University's School of Computer Science. His research is concerned with human aspects of software development, including program understanding, collaborative work, and documentation usability. He spends too much of his research time developing software, and for the past few years has been working on the eMoose memory aid for software developers (http://emoose.cs.cmu.edu). Prior to his doctoral studies he developed software at Intel and at IBM Research. He also taught courses on software development at the Israel Institute of Technology, where he received his M.Sc. and B.Sc. degrees in Computer Science.

This session is part of the curated collection of short talks titled
"Seeing the Forest for The Trees: Sifting Through Javadoc and Code"

Slides

Gold sponsors

IBM Corporation

Windriver logo

JBoss

Sun Microsystems

SOPERA

BLU AGE

BIRT Exchange by Actuate

Silver sponsors

Innovations Software Technology

Google

Genuitec

Instantiations

itemis

EclipseSource

Innovent Solutions

SAP Business Objects

Hardware Sponsor

Cisco

Lanyard Sponsor

Intel logo



report a problem with this page