uri dekel - eclipsecon 2009 talk - "you probably should be reading this…" - getting...

1

Uri Dekel

Institute for Software Research

Carnegie Mellon University

EclipseCon 2009

http://emoose.cs.cmu.edu

You probably should be reading

this…Getting people to read your Javadocs with eMoose

Early version (03/20/2009)

Final slides will change

2 “You probably should be reading this…”, EclipseCon

2009

Why Javadocsare like tribbles…

They are attached to everything we see

They all have a similar form

More are being generated all the time

We will never catch up with all of them

Star Trek images owned by Paramount Pictures

Corporation

Intro Problem Tips eMoos

e


2009

But…

Sometimes they can alert us to things we weren’t

aware of…


e


2009

And…

The consequences of ignoring them can be

severe…


e


2009

I’m here to…

Make you rethink how you read and write method

Javadocs

Suggest ways to organize Javadoctext for your

readers

Help them read the right things!

Present a tool that can help attract developers to

specific calls that have important caveats


e


2009

Specifications

All Javadocscontain specifications

Necessary for understanding everything about

the function

Possible to use function correctly without ever

reading


e


2009

Specifications example (Java 1.4)


e


2009

Directive example (Java 1.6):


e


2009

Directives

Provide information that may directly affect client

Imperative – “Must do X!” or “Must not do X!”

Informative – “Beware of X!” or “You should

know X…”

Only nontrivial and potentially unexpected details

e.g., “Parameter must not be null” is too

common


e

10

The problem…


e


2009

Directives can be lost within the text…


e


2009

Most code fragments make many calls


e


2009

Impractical to read every target


e


2009

Directives can hide in unexpected locations…


e

Which of these calls would you be most likely to

investigate?


2009

Directives can hide in unexpected locations…


e


2009

Newly added calls may also hide

directives


e


2009

Some methods can behave in unexpected ways


e


2009

There may be a surprise in an overridden

version…


e

19

What you can do as

a documentation writer….


e


2009

What you can do…

Make it easier for readers of your

documentation to become aware of

directives within it!


e


2009

Make every clause visible!

Use visible vertical space between clauses

Avoid combining unrelated details in same

paragraph


e


2009

Draw attention with emphasizing terms

“Note that…”

“Warning…”

“Be aware that…”

“Important!”

DON’T BE AFRAID OF SHOUTING!


e


2009

Take reading behavior into account

Readers generally go top-down

Chances of reading decrease with distance

Chances of scrolling in Javadochover are low

Readers often ignore tag areas

Place main points first (e.g., instructions before rationale)

Place most important point early in the sentence


e


2009

Separate materials by audience

Instance users

Authors of overriding methods

Maintainers / testers /etc.


e


2009

Consider adding safety checks

Documenting a contract does not mean it will be

followed!

Readers can still miss directives in JavaDocs

Readers may never read the JavaDocs


e


2009

What you can’t do…

Signal to clients that they may benefit

from the documentation of your method


e

27

eMoose

Intro ProblemTips eMoos

e


2009

Goal #1

Make you aware of calls whose targets have

directives

Help you decide what to investigate


e


2009

Goal #2

When you choose to investigate a method’s

Javadoc,

help you quickly determine:

What are the directives

Whether to actually read the method text


e


2009

The eMoose tool

An Eclipse plug-in for Java developers

Research prototype

Available for free

Open source in future

Does not require server

Future version will support client-server model

Sharing directives and ratings in real time

Additional episodic functionality to serve as

memory-aid


e


2009

Knowledge space

The eMoose plug-in maintains a “knowledge

space”

Consists of “Knowledge items”

Generally correspond to directives

Each associated with a specific method / class

Each has a line of text and a type


e


2009

Decorating calls

eMoose constantly scans the Java editor for

method calls

Decoration appears if target has associated

knowledge item

With new calls, decoration appears right after

creation

Optional: decorates if overriding version in

possible dynamic type has associated knowledge

item


e


2009

Augmenting the JavaDoc hover

Additional pane specifically lists directives

Users quickly understand why call was decorated


e


2009

JavaDoc hover in polymorphism


e


2009

Rating directives

Every directive has a “base rating” (0 to 5, 3 is

default)

Users can also rate directives in JavaDoc hover

Average rating used to filter and adjust decoration

contrast


e


2009

Actual impact of eMoose

Does not force users to investigate every call

Merely offers another cue that users factor into

decisions

May make the difference when…

Call could be relevant but there are no other

cues

Call is decorated when users do not expect it to

be

Augmented hover allows users to quickly

eliminate calls


e


2009

Limitations and drawbacks

eMoose is not an automatic conformance

checking tool

Relevancy to current calling context not

considered

eMoose usefulness depends on directives quality

Additional annotations could be distracting

May require increasing default heap size


e

38

Populating the Knowledge Space


e


2009

All active //TODO comments in the code


e


2009

Why tag your own non-API code?

Help you and your peers remember special

instructions for using functions in the codebase

Just because it’s in the codebase, doesn’t mean it’s

straightforward

Directives are the things you’re documenting anyway

Important reminders, caveats, and notes to others

Specifications are what you usually put off…

eMoose does not require much effort for tagging


2009

Tagging your own code

Just tag directives explicitly!

@tag usage.XXXXX: YYYYY

@tag usage.XXXXX –rating=“Z”: YYYYYY

Place in Javadocblock or in internal comment

All tags automatically highlighted – easier to spot when

browsing

Tags distributed with source code

Users without eMoose can still see tags

You’ve made directives easier to spot in the text!


2009

Why tag your API code?

Tagging makes you think about directives that affect

clients

Tags are easy to spot when viewing Javadocswithout

eMoose

Clients do not need your API source code

Easy to distribute

As standalone XML

As XML files distributed via Eclipse plug-ins

Via a central server (Future)


2009

Tagging third-party APIs

eMoose makes it possible to tag third-party APIs

Acquire source code of public APIs

Add tags in local source code

Export directive collections and distribute

eMoose comes with collections libraries for JDK and

Eclipse API

I am slowly adding more

Can be done collaboratively


2009

Directive types - Imperative

Restriction e.g., "don't invoke from the UI thread”

e.g., "To be called only from debug infrastructure”

Protocol e.g., "don't invoke this before you invoked X”

e.g., "remember to notify Y after calling this".

Locking

Parameter e.g., Send only decoded strings

Return e.g., Client responsible for releasing returned system resource

e.g., Changes to returned set may affect original


e


2009

Directive types - Informative

Limitation

Performance

Sideeffect

Threading

Alternative

Recommendation

Security


e

46

Homepage:


Update site:

http://emoose.cs.cmu.edu/dist/updatesite

http://emoose.cs.cmu.edu/dist/updatesite_mac

Try eMoose today !


e


http://emoose.cs.cmu.edu/dist/updatesite

47

Backup


2009

What’s in a JavaDoc block?

(Based on Sun’s official guidelines)

Start with a “summary sentence containing a concise but

complete description of the API item”

Continue with an “implementation independent”

description and specification that must include:

Boundary conditions

Parameter ranges

Corner cases

Sufficient to create test plan for conformance

Standard tags for parameters, returns values, exceptions

Must include everything, even if trivial or redundant!


2009

What else is in JavaDoc block?

In our survey of core APIs we also found:

Instructions for subclasses

Not relevant for clients of the supertype/superinterface

Instructions for maintainers

May expose implementation

Explanation of terminology

Issues relevant to the API as a whole

Issues relevant to groups of methods

Instructions on how to accomplish other tasks


2009

eMoose study

Goal: evaluate potential benefits and distractions

We used the three tasks seen earlier

26 subjects (primarily experienced MS students)

In each task, half used eMoose, half didn’t

Had 15 minutes to identify the bug

We expected to compare completion time


2009

eMoose study results


2009

Lab Study - Polymorphism

Two polymorphism tasks

Complicated data structure to see if developers consider

possibility of conformance violation

Simpler data structures question to see if inclusion of

numerous dynamic types beneficial or not

Results:

All 13 experimental group found issue

Only 3 of 12 controls considered possibility of conformance violation

Seeing details from overriding methods more effective than searching

API

Need some filtering of unrelated subtypes

uri dekel - eclipsecon 2009 talk - "you probably should be reading this…" - getting...

Technology

aware of directives

unexpected detailse

specific calls

specificationsall javadocs

added calls

specifications example

directive example java

right things