Comment soup with a pinch of types, served in a leaky...
Transcript of Comment soup with a pinch of types, served in a leaky...
Comment soup with a pinch of types, served in a leaky bowl
Pooja Rani Manuel Leuenberger
Software Composition Group Bern, Switzerland
!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?
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
Playground to play with code
Developers express their code
!5
Playground to play with words
Developers express themselves
!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
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
/** * 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
asdasd For the sake of commenting
Warning
Link
Dependency
Random information
Excitement, Future
discussion Word of advice
Coding guideline
Warning
Link
Dependency
Random information
Excitement, Future
discussion Word of advice
Coding guideline
!12
15% comments
85% code
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
0
2000
4000
6000
8000
1 2 3 4 5 6 7
Pharo versions
#C
lass
es
Without comments
With comments
Evolution of Class Comments
Evolution of Class Comments
!15
Pharo versions
#C
lass
es
1 2 3 4 5 6 7
Without comments
With comments
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
Developers are guided by a default template
!17
!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
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
Num
ber
of c
lass
es
0
750
1'500
2'250
3'000
Intent
Responsibility
Collaborators
Public API
Example
Internal Details Instance Variable
Template sections found in classes
Template sections6000 classesPharo 7
!21
Num
ber o
f cla
sses
0
35
69
104
138
Intent
Responsibility
Collaborators
Public API
Example
Internal Details Instance Variable
Template sections found- Manual analysis
Template sections138 random classesPharo 7
!22
Class ReferencesWarnings
LinksSteps
PreconditionObservations
LicenseSuggestionsDependency
Reference to external docsClarification
ExtensionDiscourse
Coding guideline
Number of classes
0 10 20 30 40
Extra Information - Manual analysis
Extra categories 100 random classesPharo 7
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
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
PreconditionLicense
Suggestions
Observations
Comment Soup
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
PreconditionLicense
Suggestions
Observations
Template Inspired
Extra but frequent
Extra but rare
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
Comments of length 2-5 lines, have lengthy sentences
Use first person pronouns
Writing style
Different warning words
No formatting standards followed
Inconsistent parentheses
– Penelope J. Corfield
“All people are living histories – which is why History matters”
!1
And now for something completely different
Gardening the Ecosystem
!2
The EMF is dead, long live the EMF!
!3
!4
And now for something completely different
I am lazy
!5
I am lazy
very, very lazy
!6
Swapping dependencies
!7
A Pinch of Types
How gradual types can be useful for migration
!8
!9
And
now
for
some
thin
g co
mple
tely
dif
fere
nt
The Leaky Bowl
A startling encounter in the VM world
!10
How to write two lines of code in two months
!11
How to write two lines of code in two months
- (void) pumpRunLoopEventSendA
ndSignal:(BOOL)signal {
@autoreleasepool {
... } }
!12
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