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

Abstract:
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 is one of the most important contents in the README file for demonstrating the usage of software and APIs. Presenting easy to comprehend code snippets are preferred by developers to quickly understand the usage and features of the software. However, README files may contain proficient code snippets due to readability and performance reasons. 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 and 7% of independent elements in code snippets of the README files. However, developers may present proficient elements in code snippets for Application Framework, Quality Assurance, and User Interface libraries. Thus, we encourage developers to (i) write basic README files to attract more newcomers or (ii) write proficient README files to introduce effective usage of PyPI libraries.