How Do Developers Document Database Usages in Source Code?
Mario Linares-Vasquez, Boyang Li, Christopher Vendome, and Denys Poshyvanyk
ASE 2015
Database-centric application (DCA)
DCAs are software systems that rely on databases to persist records using database objects.
Database-centric application (DCA)
DCAs are software systems that rely on databases to persist records using database objects.
Challenges
Challenges
DBManager.getAllInfoByStudentID ()
ID Num PWD Gender Address Year …
… … … … … …
… … … … … …
STUDENT
Challenges
DBManager.getAllInfoByStudentID ()
ID Num PWD Gender Address Year …
… … … … … …
… … … … … …
STUDENT
ID Num PWD …
… … …
… … …
ST_LOGIN
ID Gender Address Year …
… … … … …
… … … … …
ST_DETAILS
Challenges
DBManager.getAllInfoByStudentID ()
ID Num PWD Gender Address Year …
… … … … … …
… … … … … …
STUDENT
ID Num PWD …
… … …
… … …
ST_LOGIN
ID Gender Address Year …
… … … … …
… … … … …
ST_DETAILS
getSTLogin() getSTDetails()
Challenges
UI.student.buttonClickShowAllInfo()
UI.student.quaryAllInfoByID ()
DBManager.getAllInfoByStudentID ()
ID Num PWD Gender Address Year …
… … … … … …
… … … … … …
STUDENT
ID Num PWD …
… … …
… … …
ST_LOGIN
ID Gender Address Year …
… … … … …
… … … … …
ST_DETAILS
getSTLogin() getSTDetails()
Challenges
• How the model is described by a schema • How the database is used in the source code
Related works
Related works
Related works
Related works
No previous work has been done to understand database documentation practices at source code level.
Goal
How Do Developers Document Database Usages in Source Code?
381,161 projects
Methodology
381,161 projects
Identified the projects using SQL 18,828 projects
Methodology
381,161 projects
Identified the projects using SQL 18,828 projects
≥ 1 3,113 projects ≥ 1
Methodology
A survey
A mining-based analysis
3,113 projects
Methodology
A survey
A mining-based analysis
with
147 developers
on
33,045 methods
3,113 projects
Methodology
A survey
A mining-based analysis
with
147 developers
on
33,045 methods
Results
Results
3,113 projects
Methodology
RQ1. Do developers document database-related methods
RQ2. Do developers update comments for database-related methods
RQ3. How difficult is to understand the database schema constraints along call-chains
Research Questions
RQ1. Do developers comment methods in source code that locally execute SQL queries and statements?
SQ1. Do you add/write documentation comments to methods in the source code?
SQ2. Do you write source code comments detailing database schema constraints?
Yes No
122(82.99%)
25(17.01%)
Yes No
32(21.77%)
115(78.23%) Yes No Yes No
32(21.77%)
115(78.23%)
Yes No
32(21.77%)
115(78.23%)
RQ1. Do developers comment methods in source code that locally execute SQL queries and statements?
“The database schema and documentation takes care of that. I can always look at the table definition very easily.”
“Comments related to the database schema and its constraints I consider to be irrelevant to the code using it. The schema, its details, and any quirks about it should be outlined in a separate document.” Yes No
32(21.77%)
115(78.23%)
RQ1. Do developers comment methods in source code that locally execute SQL queries and statements?
23%
7,595 (23%)
In the 3,113 projects, we identified a total of 33,045 methods invoking SQL ueries/statements.
Yes No
32(21.77%)
115(78.23%)
RQ1. Do developers comment methods in source code that locally execute SQL queries and statements?
SQ3. How often do you find outdated comments in source code?
SQ4. When you make changes to database related methods, how often do you update comments?
Never Rarely SometimesFairly Often Always
29(19.73%)
118(80.27%)
RQ2. Do developers update comments of database-related methods during the evolution of a system?
SQ3. How often do you find outdated comments in source code?
SQ4. When you make changes to database related methods, how often do you update comments?
Never Rarely SometimesFairly Often Always
31(21.08%)
116(78.92%)
Never Rarely SometimesFairly Often Always
29(19.73%)
118(80.27%)
RQ2. Do developers update comments of database-related methods during the evolution of a system?
3,113 projects
264 projects
8.5% Had explicit releases
RQ2. Do developers update comments of database-related methods during the evolution of a system?
3,113 projects
264 projects
8.5% Had explicit releases
2,662 methods (Invoke SQL)
RQ2. Do developers update comments of database-related methods during the evolution of a system?
3,113 projects
264 projects
8.5% Had explicit releases
2,662 methods (Invoke SQL)
618 methods
23.2% were updated
RQ2. Do developers update comments of database-related methods during the evolution of a system?
3,113 projects
264 projects
8.5% Had explicit releases
2,662 methods (Invoke SQL)
618 methods
23.2% were updated
512 methods
82.8% didn’t updated comments
RQ2. Do developers update comments of database-related methods during the evolution of a system?
3,113 projects
264 projects
8.5% Had explicit releases
2,662 methods (Invoke SQL)
618 methods
23.2% were updated
512 methods 106 methods
82.8% didn’t updated comments
17.2% updated comments
RQ2. Do developers update comments of database-related methods during the evolution of a system?
106 methods
1 1
3 14
21 4
0 4
2 56
0 10 20 30 40 50 60
(0%,10%]
(10%,20%]
(20%,30%]
(30%,40%]
(40%,50%]
(50%,60%]
(60%,70%]
(70%,80%]
(80%,90%]
(90%,100%]
frequency that the comments were updated when the method was modified
RQ2. Do developers update comments of database-related methods during the evolution of a system?
106 methods
1 1
3 14
21 4
0 4
2 56
0 10 20 30 40 50 60
(0%,10%]
(10%,20%]
(20%,30%]
(30%,40%]
(40%,50%]
(50%,60%]
(60%,70%]
(70%,80%]
(80%,90%]
(90%,100%]
frequency that the comments were updated when the method was modified
40(37.73%)
RQ2. Do developers update comments of database-related methods during the evolution of a system?
SQ5. How difficult is it to trace the schema constraints (e.g., foreign key violations) from the methods with SQL statements to top-level method callers
Very Easy Easy ModerateHard Very Hard
50(34.01%)
97(65.99%)
RQ3. How difficult is it for developers to understand propagated schema constraints along call-chains?
Lessons learnt
(i) Documenting database usages and constraints is not a common practice in source code methods
(ii) Developers do not update comments when changes are done to database-related methods
(iii) Tracing schema constraints through call-chains in the call graph is not an easy task in most of the cases
Lessons learnt
(i) Documenting database usages and constraints is not a common practice in source code methods
(ii) Developers do not update comments when changes are done to database-related methods
(iii) Tracing schema constraints through call-chains in the call graph is not an easy task in most of the cases
Documentation
Automation
Calling context
Summary
Summary
Summary
Summary