What do class comments tell us?An investigation of comment evolution and practices in Pharo Smalltalk

What do class comments tell us?

An investigation of comment
evolution and practices in Pharo
Smalltalk
Pooja Rani, Sebastiano Panichella, Manuel
Leuenberger, Mohammad Ghafari, Oscar Nierstrasz
Journal First

/**
* A class representing a window on the screen.
*
* For example:
* <pre>
* Window win = new Window(parent);
* win.show();
* </pre>
*
* @author Sami Shaio
* @version 1.13, 06/08/06
* @see java.awt.BaseWindow
*/
class Window extends BaseWindow {
…
}
2
Motivation
High-quality code comments assist developers
- Dekel et al. 2009
Java class comment

/**
* A class representing a window on the screen.
*
* For example:
* <pre>
* Window win = new Window(parent);
* win.show();
* </pre>
*
* @author Sami Shaio
* @version 1.13, 06/08/06
* @see java.awt.BaseWindow
*/
class Window extends BaseWindow {
…
}
3
Motivation
Java class comment
Different languages use different conventions to write comments
Smalltalk class comment

9
Class comments are a main source of documentation

No strict comment conventions, such as tags

Lack of quality assessment tools

Lack of empirical studies

Challenges

10

No strict comment conventions such as tags



Challenges

11




Challenges

12




Challenges

13




Requires empirical knowledge
Using previous techniques a non-trivial task
Challenges

14
We study Smalltalk class comments

15
We analyse from three perspectives
P1
Commenting trend
Comment
adherence to
template
P3
Comment
information types
P2

16
P1
Commenting trend
Comment
adherence to
template
P3
Comment
information types
P2
How often developers

write?

17
Commenting trend
https://en.wikipedia.org/wiki/Pharo https://pharo.org/

18
Commenting trend
■ Pharo software system (first appeared in 2008)

■ Study its seven versions from 2008-2019 (11 years)
https://en.wikipedia.org/wiki/Pharo https://pharo.org/

19
0
1000
2000
3000
4000
5000
6000
7000
8000
2 3 4 5 6 7
#
Classes
Pharo versions
New classes
Old classes unchanged
Old classes only comment changed
Old classes only code changed
Old classes comment and code changed
50% of comment changes were related to code changes

20
0
100
200
300
400
500
600
700
800
2 3 4 5 6 7
#
Classes
Pharo versions
Comments removed of old classes
Comments added to old classes
Comments updated of old classes
developers add or update comment of old classes

21
P1
Commenting trend
Comment
adherence to
template
P3
Comment
information types
P2
What do developers

write?

22
Implementation
details
Intent
Example
Unlike Java and Python, there is no comment taxonomy
Smalltalk class comments

23
Information types in Smalltalk
7 Pharo versions

2008-2019

364 sample comments

Smalltalk class comments contain 23 types of information

24
Color scale according to number of comments falling into a category
0 25 52
0 26 52
1 (52)
2 (52)
3 (52)
4 (52)
5 (52)
6 (52)
7 (52)
O
t
h
e
r
L
i
c
e
n
s
e
D
e
p
e
n
d
e
n
c
i
e
s
C
o
n
t
r
a
c
t
s
O
b
s
e
r
v
a
t
i
o
n
s
R
e
c
o
m
m
e
n
d
a
t
i
o
n
s
E
x
t
e
n
s
i
o
s
L
i
n
k
s
D
i
s
c
o
u
r
s
e
W
a
r
n
i
n
g
s
C
o
d
i
n
g
G
u
i
d
e
l
i
n
e
s
N
a
m
i
n
g
C
o
n
v
e
n
t
i
o
n
s
T
o
d
o
c
o
m
m
e
n
t
s
C
l
a
s
s
R
e
f
e
r
e
n
c
e
s
S
u
b
c
l
a
s
s
e
s
E
x
p
l
a
n
a
t
i
o
n
R
e
f
e
r
e
n
c
e
O
t
h
e
r
R
e
s
o
u
r
c
e
s
I
m
p
l
e
m
e
n
t
a
t
i
o
n
P
o
i
n
t
s
E
x
a
m
p
l
e
s
K
e
y
M
e
s
s
a
g
e
s
I
n
s
t
a
n
c
e
V
a
r
i
a
b
l
e
s
C
o
l
l
a
b
a
r
t
o
r
s
R
e
s
p
o
n
s
i
b
i
l
i
t
y
I
n
t
e
n
t
Categories
Pharo
versions
(total
classes)
Smalltalk class comments contain 23 types of information
Information types in Smalltalk

25
0 25 52
0 26 52
1 (52)
2 (52)
3 (52)
4 (52)
5 (52)
6 (52)
7 (52)
O
t
h
e
r
L
i
c
e
n
s
e
D
e
p
e
n
d
e
n
c
i
e
s
C
o
n
t
r
a
c
t
s
O
b
s
e
r
v
a
t
i
o
n
s
R
e
c
o
m
m
e
n
d
a
t
i
o
n
s
E
x
t
e
n
s
i
o
s
L
i
n
k
s
D
i
s
c
o
u
r
s
e
W
a
r
n
i
n
g
s
C
o
d
i
n
g
G
u
i
d
e
l
i
n
e
s
N
a
m
i
n
g
C
o
n
v
e
n
t
i
o
n
s
T
o
d
o
c
o
m
m
e
n
t
s
C
l
a
s
s
R
e
f
e
r
e
n
c
e
s
S
u
b
c
l
a
s
s
e
s
E
x
p
l
a
n
a
t
i
o
n
R
e
f
e
r
e
n
c
e
O
t
h
e
r
R
e
s
o
u
r
c
e
s
I
m
p
l
e
m
e
n
t
a
t
i
o
n
P
o
i
n
t
s
E
x
a
m
p
l
e
s
K
e
y
M
e
s
s
a
g
e
s
I
n
s
t
a
n
c
e
V
a
r
i
a
b
l
e
s
C
o
l
l
a
b
a
r
t
o
r
s
R
e
s
p
o
n
s
i
b
i
l
i
t
y
I
n
t
e
n
t
Categories
Pharo
versions
(total
classes)

26
0 25 52
0 26 52
1 (52)
2 (52)
3 (52)
4 (52)
5 (52)
6 (52)
7 (52)
O
t
h
e
r
L
i
c
e
n
s
e
D
e
p
e
n
d
e
n
c
i
e
s
C
o
n
t
r
a
c
t
s
O
b
s
e
r
v
a
t
i
o
n
s
R
e
c
o
m
m
e
n
d
a
t
i
o
n
s
E
x
t
e
n
s
i
o
s
L
i
n
k
s
D
i
s
c
o
u
r
s
e
W
a
r
n
i
n
g
s
C
o
d
i
n
g
G
u
i
d
e
l
i
n
e
s
N
a
m
i
n
g
C
o
n
v
e
n
t
i
o
n
s
T
o
d
o
c
o
m
m
e
n
t
s
C
l
a
s
s
R
e
f
e
r
e
n
c
e
s
S
u
b
c
l
a
s
s
e
s
E
x
p
l
a
n
a
t
i
o
n
R
e
f
e
r
e
n
c
e
O
t
h
e
r
R
e
s
o
u
r
c
e
s
I
m
p
l
e
m
e
n
t
a
t
i
o
n
P
o
i
n
t
s
E
x
a
m
p
l
e
s
K
e
y
M
e
s
s
a
g
e
s
I
n
s
t
a
n
c
e
V
a
r
i
a
b
l
e
s
C
o
l
l
a
b
a
r
t
o
r
s
R
e
s
p
o
n
s
i
b
i
l
i
t
y
I
n
t
e
n
t
Categories
Pharo
versions
(total
classes)

27
High-level
overview
0 25 52
0 26 52
1 (52)
2 (52)
3 (52)
4 (52)
5 (52)
6 (52)
7 (52)
O
t
h
e
r
L
i
c
e
n
s
e
D
e
p
e
n
d
e
n
c
i
e
s
C
o
n
t
r
a
c
t
s
O
b
s
e
r
v
a
t
i
o
n
s
R
e
c
o
m
m
e
n
d
a
t
i
o
n
s
E
x
t
e
n
s
i
o
s
L
i
n
k
s
D
i
s
c
o
u
r
s
e
W
a
r
n
i
n
g
s
C
o
d
i
n
g
G
u
i
d
e
l
i
n
e
s
N
a
m
i
n
g
C
o
n
v
e
n
t
i
o
n
s
T
o
d
o
c
o
m
m
e
n
t
s
C
l
a
s
s
R
e
f
e
r
e
n
c
e
s
S
u
b
c
l
a
s
s
e
s
E
x
p
l
a
n
a
t
i
o
n
R
e
f
e
r
e
n
c
e
O
t
h
e
r
R
e
s
o
u
r
c
e
s
I
m
p
l
e
m
e
n
t
a
t
i
o
n
P
o
i
n
t
s
E
x
a
m
p
l
e
s
K
e
y
M
e
s
s
a
g
e
s
I
n
s
t
a
n
c
e
V
a
r
i
a
b
l
e
s
C
o
l
l
a
b
a
r
t
o
r
s
R
e
s
p
o
n
s
i
b
i
l
i
t
y
I
n
t
e
n
t
Categories
Pharo
versions
(total
classes)

0 25 52
0 26 52
1 (52)
2 (52)
3 (52)
4 (52)
5 (52)
6 (52)
7 (52)
O
t
h
e
r
L
i
c
e
n
s
e
D
e
p
e
n
d
e
n
c
i
e
s
C
o
n
t
r
a
c
t
s
O
b
s
e
r
v
a
t
i
o
n
s
R
e
c
o
m
m
e
n
d
a
t
i
o
n
s
E
x
t
e
n
s
i
o
s
L
i
n
k
s
D
i
s
c
o
u
r
s
e
W
a
r
n
i
n
g
s
C
o
d
i
n
g
G
u
i
d
e
l
i
n
e
s
N
a
m
i
n
g
C
o
n
v
e
n
t
i
o
n
s
T
o
d
o
c
o
m
m
e
n
t
s
C
l
a
s
s
R
e
f
e
r
e
n
c
e
s
S
u
b
c
l
a
s
s
e
s
E
x
p
l
a
n
a
t
i
o
n
R
e
f
e
r
e
n
c
e
O
t
h
e
r
R
e
s
o
u
r
c
e
s
I
m
p
l
e
m
e
n
t
a
t
i
o
n
P
o
i
n
t
s
E
x
a
m
p
l
e
s
K
e
y
M
e
s
s
a
g
e
s
I
n
s
t
a
n
c
e
V
a
r
i
a
b
l
e
s
C
o
l
l
a
b
a
r
t
o
r
s
R
e
s
p
o
n
s
i
b
i
l
i
t
y
I
n
t
e
n
t
Categories
Pharo
versions
(total
classes)
28
High-level
overview
Conversation
exchanged

29
0 25 52
0 26 52
1 (52)
2 (52)
3 (52)
4 (52)
5 (52)
6 (52)
7 (52)
O
t
h
e
r
L
i
c
e
n
s
e
D
e
p
e
n
d
e
n
c
i
e
s
C
o
n
t
r
a
c
t
s
O
b
s
e
r
v
a
t
i
o
n
s
R
e
c
o
m
m
e
n
d
a
t
i
o
n
s
E
x
t
e
n
s
i
o
s
L
i
n
k
s
D
i
s
c
o
u
r
s
e
W
a
r
n
i
n
g
s
C
o
d
i
n
g
G
u
i
d
e
l
i
n
e
s
N
a
m
i
n
g
C
o
n
v
e
n
t
i
o
n
s
T
o
d
o
c
o
m
m
e
n
t
s
C
l
a
s
s
R
e
f
e
r
e
n
c
e
s
S
u
b
c
l
a
s
s
e
s
E
x
p
l
a
n
a
t
i
o
n
R
e
f
e
r
e
n
c
e
O
t
h
e
r
R
e
s
o
u
r
c
e
s
I
m
p
l
e
m
e
n
t
a
t
i
o
n
P
o
i
n
t
s
E
x
a
m
p
l
e
s
K
e
y
M
e
s
s
a
g
e
s
I
n
s
t
a
n
c
e
V
a
r
i
a
b
l
e
s
C
o
l
l
a
b
a
r
t
o
r
s
R
e
s
p
o
n
s
i
b
i
l
i
t
y
I
n
t
e
n
t
Categories
Pharo
versions
(total
classes)

30
0 25 52
0 26 52
1 (52)
2 (52)
3 (52)
4 (52)
5 (52)
6 (52)
7 (52)
O
t
h
e
r
L
i
c
e
n
s
e
D
e
p
e
n
d
e
n
c
i
e
s
C
o
n
t
r
a
c
t
s
O
b
s
e
r
v
a
t
i
o
n
s
R
e
c
o
m
m
e
n
d
a
t
i
o
n
s
E
x
t
e
n
s
i
o
s
L
i
n
k
s
D
i
s
c
o
u
r
s
e
W
a
r
n
i
n
g
s
C
o
d
i
n
g
G
u
i
d
e
l
i
n
e
s
N
a
m
i
n
g
C
o
n
v
e
n
t
i
o
n
s
T
o
d
o
c
o
m
m
e
n
t
s
C
l
a
s
s
R
e
f
e
r
e
n
c
e
s
S
u
b
c
l
a
s
s
e
s
E
x
p
l
a
n
a
t
i
o
n
R
e
f
e
r
e
n
c
e
O
t
h
e
r
R
e
s
o
u
r
c
e
s
I
m
p
l
e
m
e
n
t
a
t
i
o
n
P
o
i
n
t
s
E
x
a
m
p
l
e
s
K
e
y
M
e
s
s
a
g
e
s
I
n
s
t
a
n
c
e
V
a
r
i
a
b
l
e
s
C
o
l
l
a
b
a
r
t
o
r
s
R
e
s
p
o
n
s
i
b
i
l
i
t
y
I
n
t
e
n
t
Categories
Pharo
versions
(total
classes)
Internal
(Pharo
core)

0 25 52
0 26 52
1 (52)
2 (52)
3 (52)
4 (52)
5 (52)
6 (52)
7 (52)
O
t
h
e
r
L
i
c
e
n
s
e
D
e
p
e
n
d
e
n
c
i
e
s
C
o
n
t
r
a
c
t
s
O
b
s
e
r
v
a
t
i
o
n
s
R
e
c
o
m
m
e
n
d
a
t
i
o
n
s
E
x
t
e
n
s
i
o
s
L
i
n
k
s
D
i
s
c
o
u
r
s
e
W
a
r
n
i
n
g
s
C
o
d
i
n
g
G
u
i
d
e
l
i
n
e
s
N
a
m
i
n
g
C
o
n
v
e
n
t
i
o
n
s
T
o
d
o
c
o
m
m
e
n
t
s
C
l
a
s
s
R
e
f
e
r
e
n
c
e
s
S
u
b
c
l
a
s
s
e
s
E
x
p
l
a
n
a
t
i
o
n
R
e
f
e
r
e
n
c
e
O
t
h
e
r
R
e
s
o
u
r
c
e
s
I
m
p
l
e
m
e
n
t
a
t
i
o
n
P
o
i
n
t
s
E
x
a
m
p
l
e
s
K
e
y
M
e
s
s
a
g
e
s
I
n
s
t
a
n
c
e
V
a
r
i
a
b
l
e
s
C
o
l
l
a
b
a
r
t
o
r
s
R
e
s
p
o
n
s
i
b
i
l
i
t
y
I
n
t
e
n
t
Categories
Pharo
versions
(total
classes)
31
Color scale according to percentage of comments falling into a category
Internal
External
GToolkit
Seaside
Roassal
Moose
PolyMath
Petit
Pillar
O
t
h
e
r
L
i
c
e
n
s
e
D
e
p
e
n
d
e
n
c
i
e
s
C
o
n
t
r
a
c
t
s
O
b
s
e
r
v
a
t
i
o
n
s
R
e
c
o
m
m
e
n
d
a
t
i
o
n
s
E
x
t
e
n
s
i
o
s
L
i
n
k
s
D
i
s
c
o
u
r
s
e
W
a
r
n
i
n
g
s
C
o
d
i
n
g
G
u
i
d
e
l
i
n
e
s
N
a
m
i
n
g
C
o
n
v
e
n
t
i
o
n
s
T
o
d
o
c
o
m
m
e
n
t
s
C
l
a
s
s
R
e
f
e
r
e
n
c
e
s
S
u
b
c
l
a
s
s
e
s
E
x
p
l
a
n
a
t
i
o
n
R
e
f
e
r
e
n
c
e
O
t
h
e
r
R
e
s
o
u
r
c
e
s
I
m
p
l
e
m
e
n
t
a
t
i
o
n
P
o
i
n
t
s
E
x
a
m
p
l
e
s
K
e
y
M
e
s
s
a
g
e
s
I
n
s
t
a
n
c
e
V
a
r
i
a
b
l
e
s
C
o
l
l
a
b
a
r
t
o
r
s
R
e
s
p
o
n
s
i
b
i
l
i
t
y
I
n
t
e
n
t
External
projects
Total
Internal
(Pharo
core)

32
0 50 100
Internal
External
GToolkit
Seaside
Roassal
Moose
PolyMath
Petit
Pillar
O
t
h
e
r
L
i
c
e
n
s
e
D
e
p
e
n
d
e
n
c
i
e
s
C
o
n
t
r
a
c
t
s
O
b
s
e
r
v
a
t
i
o
n
s
R
e
c
o
m
m
e
n
d
a
t
i
o
n
s
E
x
t
e
n
s
i
o
s
L
i
n
k
s
D
i
s
c
o
u
r
s
e
W
a
r
n
i
n
g
s
C
o
d
i
n
g
G
u
i
d
e
l
i
n
e
s
N
a
m
i
n
g
C
o
n
v
e
n
t
i
o
n
T
o
d
o
c
o
m
m
e
n
t
s
C
l
a
s
s
R
e
f
e
r
e
n
c
e
s
S
u
b
c
l
a
s
s
e
s
E
x
p
l
a
n
a
t
R
e
f
e
r
e
n
c
e
O
t
h
e
r
R
e
s
I
m
p
l
e
m
e
n
t
a
t
i
o
n
P
o
i
E
x
a
m
p
l
e
s
K
e
y
M
e
s
s
a
g
e
s
I
n
s
t
a
n
c
e
V
a
r
i
a
b
l
e
s
C
o
l
l
a
b
a
r
t
o
r
s
R
e
s
p
o
n
s
i
b
i
l
i
t
y
I
n
t
e
n
t
External
projects
Total
Internal
External
GToolkit
Seaside
Roassal
Moose
PolyMath
Petit
Pillar
O
t
h
e
r
L
i
c
e
n
s
e
D
e
p
e
n
d
e
n
c
i
e
s
C
o
n
t
r
a
c
t
s
O
b
s
e
r
v
a
t
i
o
n
s
R
e
c
o
m
m
e
n
d
a
t
i
o
n
s
E
x
t
e
n
s
i
o
s
L
i
n
k
s
D
i
s
c
o
u
r
s
e
W
a
r
n
i
n
g
s
C
o
d
i
n
g
G
u
i
d
e
l
i
n
e
s
N
a
m
i
n
g
C
o
n
v
e
n
t
i
o
n
s
T
o
d
o
c
o
m
m
e
n
t
s
C
l
a
s
s
R
e
f
e
r
e
n
c
e
s
S
u
b
c
l
a
s
s
e
s
E
x
p
l
a
n
a
t
i
o
n
R
e
f
e
r
e
n
c
e
O
t
h
e
r
R
e
s
o
u
r
c
e
s
I
m
p
l
e
m
e
n
t
a
t
i
o
n
P
o
i
n
t
s
E
x
a
m
p
l
e
s
K
e
y
M
e
s
s
a
g
e
s
I
n
s
t
a
n
c
e
V
a
r
i
a
b
l
e
s
C
o
l
l
a
b
a
r
t
o
r
s
R
e
s
p
o
n
s
i
b
i
l
i
t
y
I
n
t
e
n
t
Categories
External
projects
Total
Core developers and external developers vary

33
P1
Commenting trend
Comment
adherence to
template
P3
Comment
information types
P2
Do developers

follow guidelines?

Each community has its own guidelines
Apache
Oracle
Google Smalltalk
PEP8/257
34
Coding style guidlines

Each community has its own guidelines
Apache
Oracle
Google Smalltalk
PEP8/257
35
State a one line of summary

Summary should be written in
fi
rst
person style

Coding style guidlines

37
Measure adherence to template

38
0 25 52
0 26 52
1 (52)
2 (52)
3 (52)
4 (52)
5 (52)
6 (52)
7 (52)
O
t
h
e
r
L
i
c
e
n
s
e
D
e
p
e
n
d
e
n
c
i
e
s
C
o
n
t
r
a
c
t
s
O
b
s
e
r
v
a
t
i
o
n
s
R
e
c
o
m
m
e
n
d
a
t
i
o
n
s
E
x
t
e
n
s
i
o
s
L
i
n
k
s
D
i
s
c
o
u
r
s
e
W
a
r
n
i
n
g
s
C
o
d
i
n
g
G
u
i
d
e
l
i
n
e
s
N
a
m
i
n
g
C
o
n
v
e
n
t
i
o
n
s
T
o
d
o
c
o
m
m
e
n
t
s
C
l
a
s
s
R
e
f
e
r
e
n
c
e
s
S
u
b
c
l
a
s
s
e
s
E
x
p
l
a
n
a
t
i
o
n
R
e
f
e
r
e
n
c
e
O
t
h
e
r
R
e
s
o
u
r
c
e
s
I
m
p
l
e
m
e
n
t
a
t
i
o
n
P
o
i
n
t
s
E
x
a
m
p
l
e
s
K
e
y
M
e
s
s
a
g
e
s
I
n
s
t
a
n
c
e
V
a
r
i
a
b
l
e
s
C
o
l
l
a
b
a
r
t
o
r
s
R
e
s
p
o
n
s
i
b
i
l
i
t
y
I
n
t
e
n
t
Categories
Pharo
versions
(total
classes)

39
31%
38%
37%
Smalltalk
Python
Java
Followed rules
31%
38%
37%
Smalltalk
Python
Java
Followed rules

40
31%
38%
37%
30%
7%
2%
Smalltalk
Python
Java
Followed rules Not followed rules
31%
38%
37%
30%
7%
2%
Smalltalk
Python
Java
Followed rules Not followed rules

41
31%
38%
37%
30%
7%
2%
40%
55%
60%
Smalltalk
Python
Java
Followed rules Not followed rules Not applicable rules
31%
38%
37%
30%
7%
2%
40%
55%
60%
Smalltalk
Python
Java
Followed rules Not followed rules Not applicable rules
Developers do not always adopt conventions (not applicable rules)

42
Developers embed 23 types of information in class
comments

Developers follow template inspired information types
more often than others

Takeaway

43
The ultimate goal of automatically assessing
comments is still far away…

44
Which information types do developers find important?

How do various information types support developers?

How to extract them automatically?

Future work

45
https://twitter.com/poojaruhal http://scg.unibe.ch/staff/Pooja-Rani
What do class comments tell us?

An investigation of comment evolution and practices in
Pharo Smalltalk
Paper

https://link.springer.com/content/pdf/10.1007/
s10664-021-09981-5.pdf

Replication Package on GitHub

https://github.com/poojaruhal/CommentAnalysisInPharo

Contact us

What do class comments tell us?An investigation of comment evolution and practices in Pharo Smalltalk

More Related Content

Similar to What do class comments tell us?An investigation of comment evolution and practices in Pharo Smalltalk (20)

Recently uploaded (20)

What do class comments tell us?An investigation of comment evolution and practices in Pharo Smalltalk