Code comments are important for program compre- hension, development, and maintenance tasks. Given the varying standards for code comments, and their unstructured or semi- structured nature, developers get easily confused (especially novice developers) about which convention(s) to follow, or what tools to use while writing code documentation. Thus, they post related questions on external online sources to seek better commenting practices. In this paper, we analyze code comment discussions on online sources such as Stack Overflow (SO) and Quora to shed some light on the questions developers ask about commenting practices. We apply Latent Dirichlet Allocation (LDA) to identify emerging topics concerning code comments. Then we manually analyze a statistically significant sample set of posts to derive a taxonomy that provides an overview of the developer questions about commenting practices. Our results highlight that on SO nearly 40% of the questions mention how to write or process comments in documentation tools and environments, and nearly 20% of the questions are about potential limitations and possibilities of documentation tools to add automatically and consistently more information in comments. On the other hand, on Quora, developer questions focus more on background information (35% of the questions) or asking opinions (16% of the questions) about code comments. We found that (i) not all aspects of comments are covered in coding style guidelines, e.g., how to add a specific type of information, (ii) developers need support in learning the syntax and format conventions to add various types of information in comments, and (iii) developers are interested in various automated strategies for comments such as detection of bad comments, or verify comment style automatically, but lack tool support to do that. PDF: https://arxiv.org/abs/2108.07648 Video: https://youtu.be/EUQINZ38ziU Replication package: https://doi.org/10.5281/zenodo.5044270

1. What do Developers Discuss about
Code Comments?
Pooja Rani, Mathias Birrer, Sebastiano Panichella
Mohammad Ghafari, Oscar Nierstrasz
University of Bern, Switzerland

2. Code Comment
2
/** Event fired when a spacer element is hidden or shown in Escalator
*
* @author Vaadin Ltd
* @since 7.7.13
*/
public class SpacerVisibility {
System.out.println(..);
}
Developers use comments to understand and maintain code.

3. Code Comment
• Style & Syntax is not enforced by complier
• Different conventions for Languages, Companies, Projects, Developers
• Confusion amongst developers
3

4. Planning Implementation Testing Releasing Maintenance
Internal Sources
External Sources
Developers' Information Needs
4

5. What Do Developers Discuss about Code Comments?
5

6. 6
Code
comment
questions
What Do Developers Discuss about Code Comments?

7. 7
Code
comment
questions
Code
comments High-level topics
RQ1
What Do Developers Discuss about Code Comments?

8. 8
Code
comment
questions
Types of questions
Code
comments High-level topics
RQ1
RQ2
What Do Developers Discuss about Code Comments?

9. 9
Code
comment
questions
Types of questions
Recommendations
Information needs
Code
comments High-level topics
RQ1
RQ2
RQ3 RQ4
What Do Developers Discuss about Code Comments?

10. 12
What Do Developers Discuss about Code Comments?

11. 13
What Do Developers Discuss about Code Comments?

12. 15
What high-level topics do developers discuss?
Code
comments
Code
comments High-level topics
RQ1

13. # Topic Name
1 Syntax & Format
2 IDEs & Editors
3 R Documentation
4 Code Conventions
5 Developing frameworks for thread commenting
6 Open-source software
7 Documentation generation
8 Thread comments in web-sites
9 Naming conventions & data types
10 Seeking documentation & learning language
18
LDA Topic modelling
Expected topics like “Documentation Generation” or “Syntax & Format”
were successfully identified by LDA.

14. # Topic Name
1 Syntax & Format
2 IDEs & Editors
3 R Documentation
4 Code Conventions
5 Developing frameworks for thread commenting
6 Open-source software
7 Documentation generation
8 Thread comments in web-sites
9 Naming conventions & data types
10 Seeking documentation & learning language
19
LDA Topics: Irrelevant Topics
‘Comment’ term is used in various environment

15. 22
What Do Developers Discuss about “Code Comment”?
Code
comments
Types of questions
Recommendations
Information needs
RQ2
RQ3 RQ4

16. 23
What Do Developers Discuss about “Code Comment”?
Code
comments
Types of questions
RQ2

17. RQ2: Types of questions
25
First
Dimension
Implementation
strategies
Implementation
problems
Error
Limitation &
Possibilities
Background
Information
Best Practice
Opinion
How to use @value tag in Javadoc
The command does not work
Contains an error message from the
exception
Is there a keyboard shortcut for block
comments?
Why is # usually introduces a comment?
What is the proper way to reference a
element in Android comments?
Are comments in code a good or bad
thing?

18. 26
0%
5%
10%
15%
20%
25%
30%
35%
40%
Implementation
Strategies
Best practice Background
Information
Limitation &
Possibilites
Implementation
Problems
Opinion Error
%
of
Question
Types
Stack overflow Quora
RQ2: Types of questions
Developers prefer different sources to know different aspects of comments

19. RQ3: Developer Information Needs
30
Second Dimension - Level 2
Syntax & format
Asking for features
Using features
Maintain
comments
Understand
documentation
Process comments
Change comment
template
........

20. 32
Comment-conventions
Programming Languages Tools
IDEs & Editors Other
Add
comments
Versioning
comments
Comments
example
Grammar
rules
Maintain
comments
Syntax &
format
Other
Asking for
features
Change comment
template
Error
Process
comments
Report
bug
Setup
Syntax &
format
Using
Feature
Asking for
features
Shortcut
Process
comments
Using
feature
Tool
setup
Change comment
template
Syntax &
format
Adopt other
language style
Asking for
feature
Asking tool
existence
Change comment
template
Understand
documentation
Using
features
Process
comments
Syntax &
format
Display
comments
Add
tags
Add
comments
Blocks/Multiline
comments
Inline
comments
Add
comments
Formatting
Color
scheme
Render
documentation
Detect
undocumented
code files
Detect todo
comments
Highlight
comments
Add more information
in comments
Generate API
documentation
Directives
Generate
documentation
Lint
Add
tags
Class
comments
Function
comments
Project
documentation
Other
Show
comments
Synchronize code
comment changes
Mulit-lingual
comments
Add more
information
Add
comments
Show inherited
comments
Add
media
Generate
documentation
Tags
Function Class
Project
Other
Function
comment
Class
comment
Project
comment
Block/
Multiline
Other
Inline
comments
Comment Highlevels
Categories found in both sources (SO and Quora)
Categories found on SO
Categories found on Quora
RQ3: Developer Information Needs

21. Syntax & format
33
Increasing efforts and trend towards Function (API) documentation

22. 36
1.1
2.2
2.2
3.2
3.2
3.2
4.3
4.3
5.4
5.4
7.5
9.7
11.8
14
22.6
0 % 5 % 10 % 15 % 20 % 25 %
Show inherited methods comments
Detect Todo comments
Detect undocumented code files
Color scheme
Highlight comments
Synchronize Code comment changes
Ask for documentation
Multi-lingual comments
Add comments
Render Documentation
Other
Show comments
Add media
Generate documentation
Add more information
% of Posts Asking for a Feature
Feautres
Developer
Ask
Developers are interesting in adding various information types in
comments such as how to add images, examples in comments
Asking for features

23. RQ4: Recommendations
37
[.net] long inline comments should start with a capital letter and end with a period.
[general] Use correct notation to write block or multiline comments.
We identified 40 comment conventions that developers recommend
on these platforms

24. Findings relevant for developers and researchers
Implication

25. Implications
40
Need of automated style checkers
Some languages do not support automated style
checkers
Adherence of comments to the
conventions
To what extent developers follow commenting
conventions
Tools to assess comment quality
Developers look for automated tools to assess
the quality of their comments
Ease of finding commenting guidelines
Developers face problems in locating
conventions

26. Future Work
• Investigate more sources (e.g. GitHub, Jira, Mailing lists)
• Survey developers to know which concerns are more important
than others
• Verifying the tool support to assess code comments
41

27. What do Developers Discuss about Code Comments?
• Preprint on Arxiv
https://arxiv.org/abs/2108.07648
• Video on YouTube
https://youtu.be/EUQINZ38ziU
• Replication Package on Zenodo
https://doi.org/10.5281/zenodo.5044270
42
http://scg.unibe.ch/staff
Contact us
https://twitter.com/poojaruhal