Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Comment soup with a pinch of types, served in a leaky bowl

114 views

Published on

Comment soup with a pinch of types, served in a leaky bowl
Talk by Pooja Rani and Manuel Leuenberger, PharoDays 2019

Published in: Technology
  • Be the first to comment

  • Be the first to like this

Comment soup with a pinch of types, served in a leaky bowl

  1. 1. Comment soup with a pinch of types, served in a leaky bowl Pooja Rani Manuel Leuenberger Software Composition Group Bern, Switzerland
  2. 2. !2 A Pinch of Types The Leaky Bowl How gradual types can be useful for migration A startling encounter in the VM world The Comment Soup How do comments evolve? How do developers write comments?
  3. 3. How do developers write comments? How do class comments evolve over time? What is the impact of template on the comments? What information is present in class comments? What is the writing style of developers? !3
  4. 4. !4 Playground to play with code Developers express their code
  5. 5. !5 Playground to play with words Developers express themselves
  6. 6. !6 Note that to encode a String as Base64, you first have to encode the characters as bytes using a character encoder. See also http://en.wikipedia.org/wiki/Base64 Part of Zinc HTTP Components. Warning Link Dependency
  7. 7. !7 Wow! I am the biezer shape 4 4 control points. Maybe we need roassal3 now with a better system for bezier lines Excitement, Future discussion
  8. 8. !8 /** * Options for connecting through a proxy * * Note that not all types may be supported, depending on * the platform and compilation options. */ Missing Java documentation
  9. 9. !9 asdasd For the sake of commenting
  10. 10. Warning Link Dependency Random information Excitement, Future discussionWord of advice Coding guideline
  11. 11. Warning Link Dependency Random information Excitement, Future discussionWord of advice Coding guideline
  12. 12. !12 15% comments 85% code
  13. 13. How do developers write comments? How do class comments evolve over time? What is the impact of template on the comments? What information is present in class comments? What is the writing style of developers? !13
  14. 14. !14 0 2000 4000 6000 8000 1 2 3 4 5 6 7 Pharo versions 
 #Classes Without comments With comments Evolution of Class Comments
  15. 15. Evolution of Class Comments !15 Pharo versions 
 #Classes 1 2 3 4 5 6 7 Without comments With comments
  16. 16. How do developers write comments? How do class comments evolve over time? What is the impact of template on the comments? What information is present in class comments? What is the writing style of developers? !16
  17. 17. Developers are guided by a default template !17
  18. 18. !18 Please comment me using the following template inspired by Class Responsibility Collaborator (CRC) design: For the Class part: State a one line summary. For example, "I represent a paragraph of text". For the Responsibility part: Three sentences about my main responsibilities - what I do, what I know. For the Collaborators Part: State my main collaborators and one line about how I interact with them. Public API and Key Messages - message one - message two - (for bonus points) how to create instances. One simple example is simply gorgeous. Internal Representation and Key Implementation Points. Implementation Points Comment markup?
  19. 19. !19 I am an abstract class to define an Item use by a tree data source of Fast table. Description ------------------------------------------------- I define the basics methods needed by a FTTreeDataSource. I use FTTreeItem to manage my elements and I am use by a FTFastTable. Public API and Key Messages ------------------------------------------------- - #data. anObject from: aFTTreeDataSource This is my constructor that is use by FTTreeDataSource and myself Example ------------------------------------------------ Should not be instanciate. Internal Representation and Key Implementation Points. ------------------------------------------------- Instance Variables dataSource: I am the dataSource that holds this Item. children: I am a collection of Items calculate by the item. I contains the chldren of the Item. Comment markup! Key Messages Intent
  20. 20. !20 Numberofclasses 0 750 1'500 2'250 3'000 Intent Responsibility Collaborators PublicA PI Exam ple InternalD etails InstanceVariable Template sections found in classes Template sections 6000 classes Pharo 7
  21. 21. !21 Numberofclasses 0 35 69 104 138 Intent Responsibility Collaborators PublicA PI Exam ple InternalD etails InstanceVariable Template sections found- Manual analysis Template sections 138 random classes Pharo 7
  22. 22. !22 Class References Warnings Links Steps Precondition Observations License Suggestions Dependency Reference to external docs Clarification Extension Discourse Coding guideline Number of classes 0 10 20 30 40 Extra Information - Manual analysis Extra categories 100 random classes Pharo 7
  23. 23. How do developers write comments? How do class comments evolve over time? What is the impact of template on the comments? What information is present in class comments? What is the writing style of developers? !23
  24. 24. What information is present in class comments? !24 Intent Responsibility Collaborators Public API Example Internal Details Instance Variable Dependency Reference to external docs ClarificationExtension Discourse Coding guideline Class References Warnings LinksSteps Precondition License Suggestions Observations Comment Soup
  25. 25. What information is present in class comments? !25 Intent Responsibility Collaborators Public API Example Internal Details Instance Variable Dependency Reference to external docs ClarificationExtension Discourse Coding guideline Class References Warnings LinksSteps Precondition License Suggestions Observations Template Inspired Extra but frequent Extra but rare
  26. 26. How do developers write comments? How do class comments evolve over time? What is the impact of template on the comments? What information is present in class comments? What is the writing style of developers? !26
  27. 27. !27 Comments of length 2-5 lines, have lengthy sentences Use first person pronouns Writing style Different warning words No formatting standards followed Inconsistent parentheses
  28. 28. – Penelope J. Corfield “All people are living histories – which is why History matters”
  29. 29. !1 And now for something completely different
  30. 30. Gardening the Ecosystem !2
  31. 31. The EMF is dead, long live the EMF! !3
  32. 32. !4 Andnowforsomething completelydifferent
  33. 33. I am lazy !5
  34. 34. I am lazy very, very lazy !6
  35. 35. Swapping dependencies !7
  36. 36. A Pinch of Types How gradual types can be useful for migration !8
  37. 37. !9 Andnowforsomething completelydifferent
  38. 38. The Leaky Bowl A startling encounter in the VM world !10
  39. 39. How to write two lines of code in two months !11
  40. 40. How to write two lines of code in two months - (void) pumpRunLoopEventSendAndSignal:(BOOL)signal { @autoreleasepool { ... } } !12
  41. 41. The Bern Experience • People put effort in commenting classes, not only for new, but also old classes • Comment template impacts developers, structure helps • The ecosystem needs love • Dynamically typed does not mean no types • Deeper integration of code transformation tools !13

×