How do Developers Improve Code Readability? An Empirical Study of Pull Requests

TL;DR

This study analyzes real-world code readability improvements made by developers in pull requests, revealing gaps in existing static analysis tools and proposing a detailed catalog of readability enhancement types.

Contribution

It provides the first empirical catalog of developer-performed readability improvements and highlights discrepancies with current static analysis tools like SonarQube.

Findings

Developers improve code to be more intuitive, modular, and less verbose.

SonarQube detected only 7% of the readability improvements.

There is significant potential to enhance static analysis tools for better readability support.

Abstract

Readability models and tools have been proposed to measure the effort to read code. However, these models are not completely able to capture the quality improvements in code as perceived by developers. To investigate possible features for new readability models and production-ready tools, we aim to better understand the types of readability improvements performed by developers when actually improving code readability, and identify discrepancies between suggestions of automatic static tools and the actual improvements performed by developers. We collected 370 code readability improvements from 284 Merged Pull Requests (PRs) under 109 GitHub repositories and produce a catalog with 26 different types of code readability improvements, where in most of the scenarios, the developers improved the code readability to be more intuitive, modular, and less verbose. Surprisingly, SonarQube only detected 26 out of the 370 code readability improvements. This suggests that some of the catalog produced has not yet been addressed by SonarQube rules, highlighting the potential for improvement in Automatic static analysis tools (ASAT) code readability rules as they are perceived by developers.