When Comments and Code Diverge : Investigating the Consequences of Bad Comments

• Main Authors: Bakhuizen, Ellinor, Landelius, Cecilia
• Format: Others
• Language: English
• Published: KTH, Skolan för elektroteknik och datavetenskap (EECS) 2019
• Subjects: Computer and Information Sciences; Data- och informationsvetenskap
• Online Access: http://urn.kb.se/resolve?urn=urn:nbn:se:kth:diva-255047

In large software development projects the majority of code comments are written at the beginning of the project and tend to not be updated when the code is rewritten. This commonly results in code with incorrect comments or no comments at all. This study intends to answer whether incorrect comments can mislead programmers and if well written comments assist programmers ininterpreting new code. Furthermore, the attitudes towards code comments are investigated. The research questions were answered with data from forms andc ode tests run on 35 engineering students. For the code tests eye trackers were used to provide a clear picture of how much the participants read the code and the associated comments. A majority of the test subjects agreed that comments are important whilst 8% considered comments to be unnecessary. 50% of the test subjects expressed positive feelings towards writing comments. The data from the eyetracker showed that the test subjects read comments and code equally. Thes tudy found that incorrect comments in many cases lead to misconceptions. Correct comments were shown to assist the programmer if the code contained library functions that the programmer was not familiar with. Regarding correct comments versus no comments at all there was no difference in readability if the code did not contain any library functions. === I stora mjukvaruprojekt skrivs majoriteten av kodkommentarerna i början av projektets livscykel och tenderar att med tiden att sluta uppdateras när koden skrivs om. Detta kan resultera i såväl okommenterad kod som felaktiga kommentarer. Denna studie avser att besvara frågeställningen om huruvida felaktiga kommentarer kan leda till att programmerare missförstår koden samt om korrekta kommentarer kan assistera programmerare vid tolkning av skriven kod. Vidare undersöktes attityder kring kodkommentarer. Frågeställningarna besvarades med data från formulär och kodtester utförda på 35 ingenjörsstudenter. Vid kodtesterna användes eye trackers för att skapa en tydlig bild av i vilken utsträckning testpersonerna läste koden och kommentarerna. En majoritet av deltagarna ansåg att kodkommentarer är viktiga, 8% ansåg kommentarer vara oviktiga och resten ställde sig neutrala. 50% av deltagarna uttryckte positiva känslor till att skriva kommentarer. Från eye trackern kunde det påvisas att deltagarna läste kommentarer i liknande utsträckning som de läste kod. Studien fann att felaktiga kommentarer i många fall leder till missförstånd. Korrekta kommentarer visades vara till hjälp då programmerare stötte på biblioteksfunktioner de inte var bekanta med. Det var däremot ingen skillnad mellan korrekta kommentarer och inga kommentarer för de kodexempel som ej innehöll biblioteksfunktioner.