Adaptation of Source Comments and API Documentation When Source Code Changes

Status

finished by Edoardo Beutler.

Final thesis (PDF, 672 KB)

Introduction

A common reason for the occurrence of maintainability problems in complex software systems is the lack of a sound software documentation. Documentation, API descriptions, or source code comments of evolving software systems are either outdated or do not exist at all. The costs of missing or outdated software documentation amount to millions of Swiss Francs. Furthermore, source code comments and API documentation are crucial for understanding source code. To get rid of misleading or outdated information, comments and API documentation have to be adapted when source code entities change. The changeability and the maintainability of software systems respectively, are influenced by when and whether such adaptations happen.

The goals of this diploma thesis

The goal of this diploma thesis is to extend the ChangeDistiller tool to enable the investigation of whether and when such comments and API documentations adaptations happen. Changes in comments and API documentation have to be extracted and mapped to source code changes. The applicability of the extraction and mapping has to be validated using a Java case study.

Task description

The first step is to investigating the state-of-the-art including:

  • Tree differencing algorithms with focus on source code changes.
  • Our taxonomy of source code changes.
  • Existing comments to source code entity mapping approaches.

The next step is concerned with getting familiar with ChangeDistiller by extending the change extraction algorithm with comment and API documentation data. This step includes:

  • The extension of the abstract syntax tree (AST) transformer to generate intermediate ASTs for comments and API documentations.
  • The storing of the corresponding source code entities in our hibernate mapped database.
  • The extension of our taxonomy of source code hanges.
  • The development of JUnit test cases to test correctness of the extensions.

The first investigation is focused on whether and when API documentation (in our case JavaDoc) is adapted to changes in method declarations. For that an Eclipse plug-in on top of ChangeDistiller and Evolizer has to be developed.

After finishing the first investigation, an approach using text similarity heuristics to map statements in the method body to comments has to be developed. The Eclipse plug-in is extended with this approach to investigate whether and when comments are adapted to source code changes.

The validation of the approach and corresponding Eclipse plug-in is done in a case study with the Azureus and/or Eclipse.

The deliverables are as follows:

When What
1st month State-of-the-art report
2nd month Extending ChangeDistiller with comment and API documentation change extraction.
3rd month Developing an Eclipse plug-in to investigate whether and when JavaDoc is adapted to changes in method declarations + case study.
5th month Developing an approach to map source code entities to comments. Integrate the approach into the Eclipse plug-in to investigate whether and when comments are adapted to source code changes + case study
last month Finishing diploma thesis

General thesis guidelines

The typical rules of academic work must be followed. "So what is a (Diploma) Thesis" describes guidelines which must be followed. At the end of the thesis, a final report has to be written. The report should clearly be organized, follow the usual academic report structure, and has to be written in English using our s.e.a.l. LaTeX-template.

Since implementing software is also part of this thesis, state-of-the-art design, coding, and documentation standards for the software have to be obeyed.

The diploma thesis has to be concluded with a final presentation for the members of the Software Evolution and Architecture Lab (s.e.a.l.).

Advisor

Beat Fluri, Prof. Harald Gall.

More information on "What is a Diploma Thesis and How to do a Diploma Thesis at IFI" is provided here.