Towards a Theory of Factors that Influence Text Comprehension of Code Documents

The design of domain-specific software systems can benefit from participatory design practices making domain experts and programmers equal, collaborating partners. The source code of such a system might be a viable communication artifact to mediate the perspectives of the two groups. However, source code written in a general-purpose programming language is often considered too difficult to comprehend for untrained readers. At the same time, it is yet unclear what makes general-purpose programming languages difficult to understand. Based on our previous study and related work from programming pedagogy and cognitive psychology, we develop an initial theory of factors that might influence the comprehensibility of source code documents by untrained readers. This theory covers factors stemming from the features of source code, factors related to the visual appearance of source code, and factors concerned with aspects independent of code documents. This chapter discusses and illustrates these potential factors and points out initial hypotheses about how these factors can influence comprehensibility.