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