reducing technical debt

Software Architecture Lab.

Reducing Technical Debt:Using Persuasive Technology for

Encouraging Software Developers to Document Code

YULIA SHMERLIN , I N F O R M AT I O N S Y S T E M S D E PA R T M E N T, U N I V E R S I T Y O F H A I FA , I S R A E L

DORON KLIGER , E C O N O M I C S D E PA R T M E N T, U N I V E R S I T Y O F H A I FA , I S R A E L

HAYIM MAKABEE , YA H O O ! R E S E A R C H L A B S , H A I FA , I S R A E L

Software Architecture Lab. 2

Documentation Debt

Technical debt is a metaphor for the gap between the current state of a software system and its hypothesized ‘ideal’ state.

Documentation debt may occur when code is created without sufficient supporting internal documentation, such as code comments.

The growth rate of comments is smaller than the growth rate of code in software projects.


Causes of Documentation Debt

The importance of comments is often overlooked by software developers.

Some developers perceive writing internal documentation as a secondary task, as opposed to writing the code itself.

Some development approaches promote the idea that good code should be self-explanatory, and thus comments are not always necessary.


Documentation Debt Consequences

Outdated or lacking documentation increases the costs of software systems maintenance.

Previous research shows that 40%- 60% of the maintenance time is spent on studying the software prior to modification because of the lack of appropriate documentation.


Research Goals

Explore and better understand developers’ reluctance to document code.

Propose efficient ways using persuasive technology to encourage programmers to document their code.


Persuasive Technology

Persuasive technology is an interactive computer technology designed with the goal of reinforcing, changing or shaping people’s attitudes or behavior.

Shaping purposes: create a behavior pattern for a specific situation which did not exist prior to using the system.


Fogg Behavior Model

Fogg Behavior Model has three factors: Motivation Ability Triggers

Behavior activation threshold: For the trigger to evoke the desired behavior, a person has to be above that threshold, in high enough level of motivation and ability.


Research Plan

We plan two studies:1. A think-aloud protocol for examining

program maintenance tasks performance.

2. A series of experiments to assess triggers for documentation.


Think-Aloud Sessions

Each subject will perform a maintenance task, namely, add functionality, on a code written and documented by another person.

We will observe: To what extent the subject relies on the code

documentation during this process. What are the important features in code

comments that help understand existing code.


Assess Triggers for Documentation

Goal: Check if the use of a documentation-triggering tool improves documentation. While exploring also the effect of

interventions on the other Fogg factors (motivation and ability).

Quantitative results: will be calculated using documentation metrics.

Qualitative results: we plan to collect qualitative data via questionnaires.


Planned Experiments

Pilot experiments with undergraduate students.

Experiment with software practitioners: During a full-day workshop. 1st stage: participants implement coding task. 2nd stage: participants extend code written by

others. Participants are divided into two groups:

Both groups are aware that their code will be extended by someone else.

One group expects that the quality of their documentation will be judged.


Conclusions

We intend to: Identify the factors affecting documentation. Devise means for increasing compliance with

documentation requirements. Create a utility, using persuasive technology

principles, for encouraging and motivating developers to document their code.

Our results may assist software practitioners to control and reduce documentation debt.