Uri Dekel Institute for Software Research Carnegie Mellon University EclipseCon 2009 http://emoose.cs.cmu.edu You probably...
Why Javadocs are like tribbles… <ul><li>They are attached to everything we see </li></ul><ul><li>They all have a similar f...
But… <ul><li>Sometimes they can alert us to things we weren’t aware of… </li></ul>Intro Problem Tips eMoose
And… <ul><li>The consequences of ignoring them can be severe… </li></ul>Intro Problem Tips eMoose
I’m here to… <ul><li>Make you rethink how you read and write method Javadocs </li></ul><ul><li>Suggest ways to organize Ja...
Specifications <ul><li>All Javadocs contain specifications </li></ul><ul><li>Necessary for understanding everything about ...
Specifications example (Java 1.4) Intro Problem Tips eMoose
Directive example (Java 1.6): Intro Problem Tips eMoose
Directives <ul><li>Provide information that may directly affect client </li></ul><ul><ul><li>Imperative – “Must do X!” or ...
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… <ul><li>Which of these calls would you be most likely to investigate? </li></...
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 T...
Make every clause visible! <ul><ul><li>Use visible vertical space between clauses </li></ul></ul><ul><ul><li>Avoid combini...
Draw attention with emphasizing terms <ul><ul><li>“ Note that…”  </li></ul></ul><ul><ul><li>“ Warning…” </li></ul></ul><ul...
Take reading behavior into account <ul><li>Readers generally go top-down </li></ul><ul><ul><li>Chances of reading decrease...
Separate materials by audience <ul><li>Instance users </li></ul><ul><li>Authors of overriding methods </li></ul><ul><li>Ma...
Consider adding safety checks <ul><li>Documenting a contract does not mean it will be followed! </li></ul><ul><ul><li>Read...
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 <ul><li>Make you aware of calls whose targets have directives </li></ul><ul><li>Help you decide what to investigat...
Goal #2 <ul><li>When you choose to investigate a method’s Javadoc,  help you quickly determine: </li></ul><ul><ul><li>What...
The eMoose tool <ul><li>An Eclipse plug-in for Java developers </li></ul><ul><li>Research prototype </li></ul><ul><li>Avai...
Knowledge space <ul><li>The eMoose plug-in maintains a “knowledge space” </li></ul><ul><li>Consists of “Knowledge items” <...
Decorating calls <ul><li>eMoose constantly scans the Java editor for method calls </li></ul><ul><li>Decoration appears if ...
Augmenting the JavaDoc hover <ul><li>Additional pane specifically lists directives </li></ul><ul><li>Users quickly underst...
JavaDoc hover in polymorphism Intro Problem Tips eMoose
Rating directives <ul><li>Every directive has a “base rating” (0 to 5, 3 is default) </li></ul><ul><li>Users can also rate...
Actual impact of eMoose <ul><li>Does not force users to investigate every call </li></ul><ul><li>Merely offers another cue...
Limitations and drawbacks <ul><li>eMoose is not an automatic conformance checking tool </li></ul><ul><li>Relevancy to curr...
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? <ul><li>Help you and your peers remember special instructions for using  functions in the c...
Tagging your own code <ul><li>Just tag directives explicitly! </li></ul><ul><ul><li>@tag usage.XXXXX: YYYYY </li></ul></ul...
Why tag your API code? <ul><li>Tagging makes you think about directives that affect clients </li></ul><ul><li>Tags are eas...
Tagging third-party APIs <ul><li>eMoose makes it possible to tag third-party APIs </li></ul><ul><li>Acquire source code of...
Directive types - Imperative <ul><li>Restriction </li></ul><ul><ul><ul><li>e.g., &quot;don't invoke from the UI thread” </...
Directive types - Informative <ul><li>Limitation </li></ul><ul><li>Performance </li></ul><ul><li>Sideeffect </li></ul><ul>...
Homepage: http://emoose.cs.cmu.edu Update site:  http://emoose.cs.cmu.edu/dist/updatesite http://emoose.cs.cmu.edu/dist/up...
Backup
What’s in a JavaDoc block? <ul><li>(Based on Sun’s official guidelines) </li></ul><ul><li>Start with a “summary sentence c...
What else is in JavaDoc block? <ul><li>In our survey of core APIs we also found: </li></ul><ul><ul><li>Instructions for su...
eMoose study <ul><li>Goal: evaluate potential benefits and distractions </li></ul><ul><li>We used the three tasks seen ear...
eMoose study results
Lab Study - Polymorphism <ul><li>Two polymorphism tasks </li></ul><ul><ul><li>Complicated data structure to see if develop...
Upcoming SlideShare
Loading in …5
×

Uri Dekel - EclipseCon 2009 Talk - "You probably should be reading this… " - Getting people to read your JavaDocs with eMoose

798 views

Published on

These are the early draft slides for my EclipseCon 2009 talk, "You probably should be reading this..." - Getting people to read your JavaDocs with eMoose.

Abstract:
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

Published in: Technology, Education
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
798
On SlideShare
0
From Embeds
0
Number of Embeds
72
Actions
Shares
0
Downloads
27
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Uri Dekel - EclipseCon 2009 Talk - "You probably should be reading this… " - Getting people to read your JavaDocs with eMoose

  1. 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. 2. Why Javadocs are like tribbles… <ul><li>They are attached to everything we see </li></ul><ul><li>They all have a similar form </li></ul><ul><li>More are being generated all the time </li></ul><ul><li>We will never catch up with all of them </li></ul>Star Trek images owned by Paramount Pictures Corporation Intro Problem Tips eMoose
  3. 3. But… <ul><li>Sometimes they can alert us to things we weren’t aware of… </li></ul>Intro Problem Tips eMoose
  4. 4. And… <ul><li>The consequences of ignoring them can be severe… </li></ul>Intro Problem Tips eMoose
  5. 5. I’m here to… <ul><li>Make you rethink how you read and write method Javadocs </li></ul><ul><li>Suggest ways to organize Javadoc text for your readers </li></ul><ul><ul><li>Help them read the right things! </li></ul></ul><ul><li>Present a tool that can help attract developers to specific calls that have important caveats </li></ul>Intro Problem Tips eMoose
  6. 6. Specifications <ul><li>All Javadocs contain specifications </li></ul><ul><li>Necessary for understanding everything about the function </li></ul><ul><li>Possible to use function correctly without ever reading </li></ul>Intro Problem Tips eMoose
  7. 7. Specifications example (Java 1.4) Intro Problem Tips eMoose
  8. 8. Directive example (Java 1.6): Intro Problem Tips eMoose
  9. 9. Directives <ul><li>Provide information that may directly affect client </li></ul><ul><ul><li>Imperative – “Must do X!” or “Must not do X!” </li></ul></ul><ul><ul><li>Informative – “Beware of X!” or “You should know X…” </li></ul></ul><ul><li>Only nontrivial and potentially unexpected details </li></ul><ul><ul><li>e.g., “Parameter must not be null” is too common </li></ul></ul>Intro Problem Tips eMoose
  10. 10. The problem… Intro Problem Tips eMoose
  11. 11. Directives can be lost within the text… Intro Problem Tips eMoose
  12. 12. Most code fragments make many calls Intro Problem Tips eMoose
  13. 13. Impractical to read every target Intro Problem Tips eMoose
  14. 14. Directives can hide in unexpected locations… <ul><li>Which of these calls would you be most likely to investigate? </li></ul>Intro Problem Tips eMoose
  15. 15. Directives can hide in unexpected locations… Intro Problem Tips eMoose
  16. 16. Newly added calls may also hide directives Intro Problem Tips eMoose
  17. 17. Some methods can behave in unexpected ways Intro Problem Tips eMoose
  18. 18. There may be a surprise in an overridden version… Intro Problem Tips eMoose
  19. 19. What you can do as a documentation writer…. Intro Problem Tips eMoose
  20. 20. What you can do… Make it easier for readers of your documentation to become aware of directives within it! Intro Problem Tips eMoose
  21. 21. Make every clause visible! <ul><ul><li>Use visible vertical space between clauses </li></ul></ul><ul><ul><li>Avoid combining unrelated details in same paragraph </li></ul></ul>Intro Problem Tips eMoose
  22. 22. Draw attention with emphasizing terms <ul><ul><li>“ Note that…” </li></ul></ul><ul><ul><li>“ Warning…” </li></ul></ul><ul><ul><li>“ Be aware that…” </li></ul></ul><ul><ul><li>“ Important!” </li></ul></ul><ul><ul><li>DON’T BE AFRAID OF SHOUTING! </li></ul></ul>Intro Problem Tips eMoose
  23. 23. Take reading behavior into account <ul><li>Readers generally go top-down </li></ul><ul><ul><li>Chances of reading decrease with distance </li></ul></ul><ul><ul><li>Chances of scrolling in Javadoc hover are low </li></ul></ul><ul><li>Readers often ignore tag areas </li></ul><ul><li>Place main points first (e.g., instructions before rationale) </li></ul><ul><li>Place most important point early in the sentence </li></ul>Intro Problem Tips eMoose
  24. 24. Separate materials by audience <ul><li>Instance users </li></ul><ul><li>Authors of overriding methods </li></ul><ul><li>Maintainers / testers /etc. </li></ul>Intro Problem Tips eMoose
  25. 25. Consider adding safety checks <ul><li>Documenting a contract does not mean it will be followed! </li></ul><ul><ul><li>Readers can still miss directives in JavaDocs </li></ul></ul><ul><ul><li>Readers may never read the JavaDocs </li></ul></ul>Intro Problem Tips eMoose
  26. 26. What you can’t do… Signal to clients that they may benefit from the documentation of your method Intro Problem Tips eMoose
  27. 27. eMoose Intro Problem Tips eMoose
  28. 28. Goal #1 <ul><li>Make you aware of calls whose targets have directives </li></ul><ul><li>Help you decide what to investigate </li></ul>Intro Problem Tips eMoose
  29. 29. Goal #2 <ul><li>When you choose to investigate a method’s Javadoc, help you quickly determine: </li></ul><ul><ul><li>What are the directives </li></ul></ul><ul><ul><li>Whether to actually read the method text </li></ul></ul>Intro Problem Tips eMoose
  30. 30. The eMoose tool <ul><li>An Eclipse plug-in for Java developers </li></ul><ul><li>Research prototype </li></ul><ul><li>Available for free </li></ul><ul><ul><li>Open source in future </li></ul></ul><ul><ul><li>Does not require server </li></ul></ul><ul><li>Future version will support client-server model </li></ul><ul><ul><li>Sharing directives and ratings in real time </li></ul></ul><ul><ul><li>Additional episodic functionality to serve as memory-aid </li></ul></ul>Intro Problem Tips eMoose
  31. 31. Knowledge space <ul><li>The eMoose plug-in maintains a “knowledge space” </li></ul><ul><li>Consists of “Knowledge items” </li></ul><ul><ul><li>Generally correspond to directives </li></ul></ul><ul><ul><li>Each associated with a specific method / class </li></ul></ul><ul><ul><li>Each has a line of text and a type </li></ul></ul>Intro Problem Tips eMoose
  32. 32. Decorating calls <ul><li>eMoose constantly scans the Java editor for method calls </li></ul><ul><li>Decoration appears if target has associated knowledge item </li></ul><ul><li>With new calls, decoration appears right after creation </li></ul><ul><li>Optional: decorates if overriding version in possible dynamic type has associated knowledge item </li></ul>Intro Problem Tips eMoose
  33. 33. Augmenting the JavaDoc hover <ul><li>Additional pane specifically lists directives </li></ul><ul><li>Users quickly understand why call was decorated </li></ul>Intro Problem Tips eMoose
  34. 34. JavaDoc hover in polymorphism Intro Problem Tips eMoose
  35. 35. Rating directives <ul><li>Every directive has a “base rating” (0 to 5, 3 is default) </li></ul><ul><li>Users can also rate directives in JavaDoc hover </li></ul><ul><li>Average rating used to filter and adjust decoration contrast </li></ul>Intro Problem Tips eMoose
  36. 36. Actual impact of eMoose <ul><li>Does not force users to investigate every call </li></ul><ul><li>Merely offers another cue that users factor into decisions </li></ul><ul><li>May make the difference when… </li></ul><ul><ul><li>Call could be relevant but there are no other cues </li></ul></ul><ul><ul><li>Call is decorated when users do not expect it to be </li></ul></ul><ul><li>Augmented hover allows users to quickly eliminate calls </li></ul>Intro Problem Tips eMoose
  37. 37. Limitations and drawbacks <ul><li>eMoose is not an automatic conformance checking tool </li></ul><ul><li>Relevancy to current calling context not considered </li></ul><ul><li>eMoose usefulness depends on directives quality </li></ul><ul><li>Additional annotations could be distracting </li></ul><ul><li>May require increasing default heap size </li></ul>Intro Problem Tips eMoose
  38. 38. Populating the Knowledge Space Intro Problem Tips eMoose
  39. 39. All active //TODO comments in the code Intro Problem Tips eMoose
  40. 40. Why tag your own non-API code? <ul><li>Help you and your peers remember special instructions for using functions in the codebase </li></ul><ul><ul><li>Just because it’s in the codebase, doesn’t mean it’s straightforward </li></ul></ul><ul><li>Directives are the things you’re documenting anyway </li></ul><ul><ul><li>Important reminders, caveats, and notes to others </li></ul></ul><ul><ul><li>Specifications are what you usually put off… </li></ul></ul><ul><li>eMoose does not require much effort for tagging </li></ul>
  41. 41. Tagging your own code <ul><li>Just tag directives explicitly! </li></ul><ul><ul><li>@tag usage.XXXXX: YYYYY </li></ul></ul><ul><ul><li>@tag usage.XXXXX –rating=“Z”: YYYYYY </li></ul></ul><ul><li>Place in Javadoc block or in internal comment </li></ul><ul><li>All tags automatically highlighted – easier to spot when browsing </li></ul><ul><li>Tags distributed with source code </li></ul><ul><li>Users without eMoose can still see tags </li></ul><ul><ul><li>You’ve made directives easier to spot in the text! </li></ul></ul>
  42. 42. Why tag your API code? <ul><li>Tagging makes you think about directives that affect clients </li></ul><ul><li>Tags are easy to spot when viewing Javadocs without eMoose </li></ul><ul><li>Clients do not need your API source code </li></ul><ul><li>Easy to distribute </li></ul><ul><ul><li>As standalone XML </li></ul></ul><ul><ul><li>As XML files distributed via Eclipse plug-ins </li></ul></ul><ul><ul><li>Via a central server (Future) </li></ul></ul>
  43. 43. Tagging third-party APIs <ul><li>eMoose makes it possible to tag third-party APIs </li></ul><ul><li>Acquire source code of public APIs </li></ul><ul><li>Add tags in local source code </li></ul><ul><li>Export directive collections and distribute </li></ul><ul><li>eMoose comes with collections libraries for JDK and Eclipse API </li></ul><ul><ul><li>I am slowly adding more </li></ul></ul><ul><ul><li>Can be done collaboratively </li></ul></ul>
  44. 44. Directive types - Imperative <ul><li>Restriction </li></ul><ul><ul><ul><li>e.g., &quot;don't invoke from the UI thread” </li></ul></ul></ul><ul><ul><ul><li>e.g., &quot;To be called only from debug infrastructure” </li></ul></ul></ul><ul><li>Protocol </li></ul><ul><ul><ul><li>e.g., &quot;don't invoke this before you invoked X” </li></ul></ul></ul><ul><ul><ul><li>e.g., &quot;remember to notify Y after calling this&quot;. </li></ul></ul></ul><ul><li>Locking </li></ul><ul><li>Parameter </li></ul><ul><ul><ul><li>e.g., Send only decoded strings </li></ul></ul></ul><ul><li>Return </li></ul><ul><ul><ul><li>e.g., Client responsible for releasing returned system resource </li></ul></ul></ul><ul><ul><ul><li>e.g., Changes to returned set may affect original </li></ul></ul></ul>Intro Problem Tips eMoose
  45. 45. Directive types - Informative <ul><li>Limitation </li></ul><ul><li>Performance </li></ul><ul><li>Sideeffect </li></ul><ul><li>Threading </li></ul><ul><li>Alternative </li></ul><ul><li>Recommendation </li></ul><ul><li>Security </li></ul>Intro Problem Tips eMoose
  46. 46. 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
  47. 47. Backup
  48. 48. What’s in a JavaDoc block? <ul><li>(Based on Sun’s official guidelines) </li></ul><ul><li>Start with a “summary sentence containing a concise but complete description of the API item” </li></ul><ul><li>Continue with an “implementation independent” description and specification that must include: </li></ul><ul><ul><li>Boundary conditions </li></ul></ul><ul><ul><li>Parameter ranges </li></ul></ul><ul><ul><li>Corner cases </li></ul></ul><ul><ul><li>Sufficient to create test plan for conformance </li></ul></ul><ul><li>Standard tags for parameters, returns values, exceptions </li></ul><ul><ul><li>Must include everything, even if trivial or redundant! </li></ul></ul>
  49. 49. What else is in JavaDoc block? <ul><li>In our survey of core APIs we also found: </li></ul><ul><ul><li>Instructions for subclasses </li></ul></ul><ul><ul><ul><li>Not relevant for clients of the supertype/superinterface </li></ul></ul></ul><ul><ul><li>Instructions for maintainers </li></ul></ul><ul><ul><ul><li>May expose implementation </li></ul></ul></ul><ul><ul><li>Explanation of terminology </li></ul></ul><ul><ul><li>Issues relevant to the API as a whole </li></ul></ul><ul><ul><li>Issues relevant to groups of methods </li></ul></ul><ul><ul><li>Instructions on how to accomplish other tasks </li></ul></ul>
  50. 50. eMoose study <ul><li>Goal: evaluate potential benefits and distractions </li></ul><ul><li>We used the three tasks seen earlier </li></ul><ul><li>26 subjects (primarily experienced MS students) </li></ul><ul><li>In each task, half used eMoose, half didn’t </li></ul><ul><ul><li>Had 15 minutes to identify the bug </li></ul></ul><ul><ul><li>We expected to compare completion time </li></ul></ul>
  51. 51. eMoose study results
  52. 52. Lab Study - Polymorphism <ul><li>Two polymorphism tasks </li></ul><ul><ul><li>Complicated data structure to see if developers consider possibility of conformance violation </li></ul></ul><ul><ul><li>Simpler data structures question to see if inclusion of numerous dynamic types beneficial or not </li></ul></ul><ul><li>Results: </li></ul><ul><ul><li>All 13 experimental group found issue </li></ul></ul><ul><ul><li>Only 3 of 12 controls considered possibility of conformance violation </li></ul></ul><ul><ul><li>Seeing details from overriding methods more effective than searching API </li></ul></ul><ul><ul><ul><li>Need some filtering of unrelated subtypes </li></ul></ul></ul>

×