Do Developers Present Proficient Code Snippets in Their README Files? An Analysis of PyPI Libraries in GitHub

A README file plays an essential role as the face of a software project and the initial point of contact for developers in Open Source Software (OSS) projects. The code snippet ranks among the most important content in the README file for demonstrating the usage of software and APIs. While easy to comprehend, code snippets are preferred by clients in order to quickly understand software usage and features. However, proficient code snippets are sometimes found in README files. In this paper, we first investigate the prevalence of each competency level of Python code snippets in the README files. Then, we analyze the relationships between the usage of proficient code snippets and topics of libraries. From our empirical study on 1, 620 README files of PyPI libraries, we find that developers mainly present 92% of basic elements in code snippets. However, developers are likely to present proficient elements in code snippets from topics about Application Framework, Quality Assurance, and User Interface. We therefore (i) encourage developers to mainly present basic code snippets in their README files to attract more newcomers, and (ii) suggest that clients try to understand proficient code snippets if they are adopting libraries from previously mentioned topics.