Recording Concerns in Source Code Using Annotations

TL;DR

This paper explores the use of concern annotations in source code to capture developer intent, demonstrating that shared annotations improve program comprehension and maintenance efficiency through empirical studies.

Contribution

It introduces concern annotations as a method for recording and sharing developer concerns, validated by multiple studies showing their effectiveness.

Findings

Shared concern annotations overlap in developers' mental models.

Annotations aid in hypothesis confirmation and feature location.

Annotations reduce comprehension and maintenance time by around 34%.

Abstract

A concern can be characterized as a developer's intent behind a piece of code, often not explicitly captured in it. We discuss a technique of recording concerns using source code annotations (concern annotations). Using two studies and two controlled experiments, we seek to answer the following 3 research questions: 1) Do programmers' mental models overlap? 2) How do developers use shared concern annotations when they are available? 3) Does using annotations created by others improve program comprehension and maintenance correctness, time and confidence? The first study shows that developers' mental models, recorded using concern annotations, overlap and thus can be shared. The second study shows that shared concern annotations can be used during program comprehension for the following purposes: hypotheses confirmation, feature location, obtaining new knowledge, finding relationships and maintenance notes. The first controlled experiment with students showed that the presence of annotations significantly reduced program comprehension and maintenance time by 34%. The second controlled experiment was a differentiated replication of the first one, focused on industrial developers. It showed a 33% significant improvement in correctness. We conclude that concern annotations are a viable way to share developers' thoughts.