Abstract
ContextPrevious studies have characterized code comments in various programming languages, showing how high quality of code comments is crucial to support program comprehension activities, and to improve the effectiveness of maintenance tasks. However, very few studies have focused on understanding developer practices to write comments. None of them has compared such developer practices to the standard comment guidelines to study the extent to which developers follow the guidelines.ObjectiveTherefore, our goal is to investigate developer commenting practices and compare them to the comment guidelines.MethodThis paper reports the first empirical study investigating commenting practices in Pharo Smalltalk. First, we analyze class comment evolution over seven Pharo versions. Then, we quantitatively and qualitatively investigate the information types embedded in class comments. Finally, we study the adherence of developer commenting practices to the official class comment template over Pharo versions.ResultsOur results show that there is a rapid increase in class comments in the initial three Pharo versions, while in subsequent versions developers added comments to both new and old classes, thus maintaining a similar code to comment ratio. We furthermore found three times as many information types in class comments as those suggested by the template. However, the information types suggested by the template tend to be present more often than other types of information. Additionally, we find that a substantial proportion of comments follow the writing style of the template in writing these information types, but they are written and formatted in a non-uniform way.ConclusionThe results suggest the need to standardize the commenting guidelines for formatting the text, and to provide headers for the different information types to ensure a consistent style and to identify the information easily. Given the importance of high-quality code comments, we draw numerous implications for developers and researchers to improve the support for comment quality assessment tools.
Highlights
Software understanding is an integral and required activity across multiple tasks in the software development life-cycle, and is critical to any software maintenance task (Siegmund and Schumann 2015; Haiduc et al 2010)
This paper offers the following contributions: 1. an overview of the Pharo commenting trends over all seven major releases till 2019, 2. an empirically validated taxonomy, called Pharo-CTM, characterizing the information types embedded in class comments written by developers, 3. a discussion of taxonomies available from the related work, and a mapping and discussion of these taxonomies compare to our taxonomy, 4. an assessment of the extent to which developer commenting practices adhere to the standard Pharo template, and 5. a publicly available dataset of manually dissected and categorized Pharo comments, including all versions of the data used for trend analysis in the replication package (RPackage 2019)
Our taxonomy study led to the finalization of Pharo-CTM, identifying 23 types of information present in the class comments The majority of these types, i.e. 21 categories, are taken from the pilot study even though several categories of the pilot study underwent the refinement process for the final Pharo-CTM
Summary
Software understanding is an integral and required activity across multiple tasks in the software development life-cycle, and is critical to any software maintenance task (Siegmund and Schumann 2015; Haiduc et al 2010). In Pharo Smalltalk, a dynamically-typed live language and environment, a class comment contains high-level design information as well as low-level implementation details, e.g., the application programming interfaces (APIs) the class provides, the instance variables it has, and its key implementation features. To write these class comments in an informative and consistent manner, different programming languages provide various coding style guidelines, such as the Oracle style guideline, PEP257. The commenting patterns and practices in Pharo have not yet been studied or analyzed
Sign-in/Register to view highlights & summary Talk to us
Join us for a 30 min session where you can share your feedback and ask us any queries you have
Schedule a callDisclaimer: All third-party content on this website/platform is and will remain the property of their respective owners and is provided on "as is" basis without any warranties, express or implied. Use of third-party content does not indicate any affiliation, sponsorship with or endorsement by them. Any references to third-party content is to identify the corresponding services and shall be considered fair use under The CopyrightLaw.
