Étude empirique des commentaires et application des techniques de résumé par extraction pour la redocumentation

La documentation des programmes aide les développeurs à mieux comprendre le code source pendant les tâches de maintenance. Toutefois, la documentation n’est pas toujours disponible ou elle peut être de mauvaise qualité. Le recours à la redocumentation s’avère ainsi nécessaire. Dans ce contexte, nous proposons de faire la redocumentation en générant des commentaires par application de techniques de résumé par extraction. Pour mener à bien cette tâche, nous avons commencé par faire une étude empirique pour étudier les aspects quantitatifs et qualitatifs des commentaires. En particulier, nous nous sommes intéressés à l’étude de la distribution des commentaires par rapport aux différents types d’instructions et à la fréquence de documentation de chaque type. Aussi, nous avons proposé une taxonomie de commentaires pour classer les commentaires selon leur contenu et leur qualité. Suite aux résultats de l’étude empirique, nous avons décidé de résumer les classes Java par extraction des commentaires des méthodes/constructeurs. Nous avons défini plusieurs heuristiques pour déterminer les commentaires les plus pertinents à l’extraction. Ensuite, nous avons appliqué ces heuristiques sur les classes Java de trois projets pour en générer les résumés. Enfin, nous avons comparé les résumés produits (les commentaires produits) à des résumés références (les commentaires originaux) en utilisant la métrique ROUGE.

Kuvausmenetelmänvalinta ja käyttöönotto ohjelmistotuoteorganisaatiossa

Useiden pitkän kehityskaaren ohjelmistojen ylläpitäminen ja kehittäminen on vaikeaa, sillä niiden dokumentaatio on vajaata tai vanhentunutta. Tässä diplomityössä etsitään ratkaisua tällaisen ohjelmiston ja sen taustalla olevan järjestelmän kuvaukseen. Tavoitteina on tukea nykyisen ohjelmiston ylläpitoa ja uuden työvoiman perehdyttämistä. Tavoitteena on myös pohjustaa uuden korvaavan ohjelmiston suunnittelua kuvaamalla nykyiseen järjestelmään sitoutunutta sovellusalueosaamista. Työssä kehitetään kuvausmenetelmä järjestelmän kuvaamiseen hierarkkisesti laitteistotason yleiskuvauksesta ohjelmiston luokkarakenteeseen sekä toiminnallisuuteen asti. Laite- ja luokkarakennekuvaukset ovat rakenteellisia kuvauksia, joiden tehtävänä on selittää järjestelmän ja sen osien kokoonpano. Toiminnallisuudesta kertovat kuvaukset on toteutettu käyttötapauskuvauksina. Työssä keskityttiin erityisesti kohdejärjestelmän keskeisen ohjelmiston ja tietokannan kuvaamiseen. Ohjelmistosta valittiin tärkeimmät ja eniten sovellusalueen tietotaitoa sisältävät osat, joista työssä luotiin esimerkkikuvaukset. Kuvauksia on kehitettyä menetelmää hyödyntäen helppo laajentaa tarpeiden mukaan paitsi ohjelmiston muihin osiin, myös laitteiston ja järjestelmän kuvaamiseen kokonaisuudessaan syvemmin.

Documentação automatizada de APIs com tutoriais gerados a partir do Stack Overflow

One of the most common forms of reuse is through API usage. However, one of the main challenges to effective usage is an accessible and easy to understand documentation. Several papers have proposed alternatives to make more understandable API documentation, or even more detailed. However, these studies have not taken into account the complexity of understanding of the examples to make these documentations adaptable to different levels of experience of developers. In this work we developed and evaluated four different methodologies to generate tutorials for APIs from the contents of Stack Overflow and organizing them according to the complexity of understanding. The methodologies were evaluated through tutorials generated for the Swing API. A survey was conducted to evaluate eight different features of the generated tutorials. The overall outcome of the tutorials was positive on several characteristics, showing the feasibility of the use of tutorials generated automatically. In addition, the use of criteria for presentation of tutorial elements in order of complexity, the separation of the tutorial in basic and advanced parts, the nature of tutorial to the selected posts and existence of didactic source had significantly different results regarding a chosen generation methodology. A second study compared the official documentation of the Android API and tutorial generated by the best methodology of the previous study. A controlled experiment was conducted with students who had a first contact with the Android development. In the experiment these students developed two tasks, one using the official documentation of Android and using the generated tutorial. The results of this experiment showed that in most cases, the students had the best performance in tasks when they used the tutorial proposed in this work. The main reasons for the poor performance of students in tasks using the official API documentation were due to lack of usage examples, as well as its difficult use.