// TODO: Help students improve commenting practices
Peter J. DePasquale, Michael E. Locasto, Lisa C. Kaczmarczyk, Mike Martinovic · 2012
One implicit purpose of writing software code is to communicate ideas. Commenting source code helps explain these ideas and provides background on the semantics of a program. Yet, enabling students to acquire good commenting practices remains difficult. Instructors can find it hard to meaningfully discuss such practices in both introductory and advanced undergraduate courses. Furthermore, comment grading is an imprecise, labor-intensive procedure at best. But just what practices should we be encouraging students to emulate? To help address these issues (learning about professional code commenting patterns and best practices, objectively grading student comments), we developed the COMTOR tool as an open source project and web service. COMTOR provides a platform for helping assess source code documentation in an objective, structured fashion. We conducted two experiments using COMTOR: one that examines a set of popular open-source Java code projects and one that measures a baseline of student-generated code comments. The latter are based on three semesters worth of data from two different undergraduate courses. Our aim is to extract knowledge about the state of professional practice in source code comments and how these properties vary over the lifetime of a project. We can then begin to make recommendations and communicate best practices (or a lack thereof) to our students.