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

Why Javadocs are 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 eMoose

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

But… Sometimes they can alert us to things we weren’t aware of… Intro Problem Tips eMoose

Sometimes they can alert us to things we weren’t aware of…

And… The consequences of ignoring them can be severe… Intro Problem Tips eMoose

The consequences of ignoring them can be severe…

I’m here to… Make you rethink how you read and write method Javadocs Suggest ways to organize Javadoc text for your readers Help them read the right things! Present a tool that can help attract developers to specific calls that have important caveats Intro Problem Tips eMoose

Make you rethink how you read and write method Javadocs

Suggest ways to organize Javadoc text for your readers

Help them read the right things!

Present a tool that can help attract developers to specific calls that have important caveats

Specifications All Javadocs contain specifications Necessary for understanding everything about the function Possible to use function correctly without ever reading Intro Problem Tips eMoose

All Javadocs contain specifications

Necessary for understanding everything about the function

Possible to use function correctly without ever reading

Specifications example (Java 1.4) Intro Problem Tips eMoose

Directive example (Java 1.6): Intro Problem Tips eMoose

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 Intro Problem Tips eMoose

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

The problem… Intro Problem Tips eMoose

Directives can be lost within the text… Intro Problem Tips eMoose

Most code fragments make many calls Intro Problem Tips eMoose

Impractical to read every target Intro Problem Tips eMoose

Directives can hide in unexpected locations… Which of these calls would you be most likely to investigate? Intro Problem Tips eMoose

Which of these calls would you be most likely to investigate?

Directives can hide in unexpected locations… Intro Problem Tips eMoose

Newly added calls may also hide directives Intro Problem Tips eMoose

Some methods can behave in unexpected ways Intro Problem Tips eMoose

There may be a surprise in an overridden version… Intro Problem Tips eMoose

What you can do as a documentation writer…. Intro Problem Tips eMoose

What you can do… Make it easier for readers of your documentation to become aware of directives within it! Intro Problem Tips eMoose

Make every clause visible! Use visible vertical space between clauses Avoid combining unrelated details in same paragraph Intro Problem Tips eMoose

Use visible vertical space between clauses

Avoid combining unrelated details in same paragraph

Draw attention with emphasizing terms “ Note that…” “ Warning…” “ Be aware that…” “ Important!” DON’T BE AFRAID OF SHOUTING! Intro Problem Tips eMoose

“ Note that…”

“ Warning…”

“ Be aware that…”

“ Important!”

DON’T BE AFRAID OF SHOUTING!

Take reading behavior into account Readers generally go top-down Chances of reading decrease with distance Chances of scrolling in Javadoc hover are low Readers often ignore tag areas Place main points first (e.g., instructions before rationale) Place most important point early in the sentence Intro Problem Tips eMoose

Readers generally go top-down

Chances of reading decrease with distance

Chances of scrolling in Javadoc hover are low

Readers often ignore tag areas

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

Place most important point early in the sentence

Separate materials by audience Instance users Authors of overriding methods Maintainers / testers /etc. Intro Problem Tips eMoose

Instance users

Authors of overriding methods

Maintainers / testers /etc.

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 Intro Problem Tips eMoose

Documenting a contract does not mean it will be followed!

Readers can still miss directives in JavaDocs

Readers may never read the JavaDocs

What you can’t do… Signal to clients that they may benefit from the documentation of your method Intro Problem Tips eMoose

eMoose Intro Problem Tips eMoose

Goal #1 Make you aware of calls whose targets have directives Help you decide what to investigate Intro Problem Tips eMoose

Make you aware of calls whose targets have directives

Help you decide what to investigate

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 Intro Problem Tips eMoose

When you choose to investigate a method’s Javadoc, help you quickly determine:

What are the directives

Whether to actually read the method text

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 Intro Problem Tips eMoose

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

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 Intro Problem Tips eMoose

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

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 Intro Problem Tips eMoose

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

Augmenting the JavaDoc hover Additional pane specifically lists directives Users quickly understand why call was decorated Intro Problem Tips eMoose

Additional pane specifically lists directives

Users quickly understand why call was decorated

JavaDoc hover in polymorphism Intro Problem Tips eMoose

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 Intro Problem Tips eMoose

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

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 Intro Problem Tips 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

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 Intro Problem Tips eMoose

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

Populating the Knowledge Space Intro Problem Tips eMoose

All active //TODO comments in the code Intro Problem Tips eMoose

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

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

Tagging your own code Just tag directives explicitly! @tag usage.XXXXX: YYYYY @tag usage.XXXXX –rating=“Z”: YYYYYY Place in Javadoc block 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!

Just tag directives explicitly!

@tag usage.XXXXX: YYYYY

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

Place in Javadoc block 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!

Why tag your API code? Tagging makes you think about directives that affect clients Tags are easy to spot when viewing Javadocs without 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)

Tagging makes you think about directives that affect clients

Tags are easy to spot when viewing Javadocs without 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)

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

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

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 Intro Problem Tips eMoose

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

Directive types - Informative Limitation Performance Sideeffect Threading Alternative Recommendation Security Intro Problem Tips eMoose

Limitation

Performance

Sideeffect

Threading

Alternative

Recommendation

Security

Homepage: http://emoose.cs.cmu.edu Update site: http://emoose.cs.cmu.edu/dist/updatesite http://emoose.cs.cmu.edu/dist/updatesite_mac Try eMoose today ! Intro Problem Tips eMoose

Backup

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!

(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!

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

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

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

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

eMoose study results

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

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