Rich Text Programming : A Tool for Code Comprehension Jayanta Majumder, Shikha Sarkar, Sambuddha Majumder Abstract This article presents the idea of using rich text for programming. Here weex- plore some new avenues opened up by a programming environment that allows developers to use rich text formatting options (eg. fonts, colours, highlighting, embedded images, notes, audio, video etc.) in their program text. We argue that this can be very useful towards enhancing program comprehension, especially in the context of maintaining large long-lived legacy systems. Computer programs are arguably the most complex creations of mankind. Having started only afew decades ago, we have already produced billions of lines of code worth trillions of dollars, and trillions of man-hours of cognitive work would be required to main- tain them. A tool that improves maintainability of such valuable assets can be a useful addition to the development toolset. The proposed rich text program- ming environment helps us take greater advantage of our sensory faculties for meaning extraction and annotation of programs. Programmer-driven semantic colouring facilitated by this approach reduces chances of programming errors and rich multimedia features enable heavily annotated code that keeps expla- nations right where they help most with code comprehension. 1 Contents 1 Introduction 1 2 The Rich Text File Format 8 3 A Richer Programming Environment 11 3.1 Richer Program Text . 11 3.2 Richer Search . 13 3.2.1 Multiple always-present search widgets and commands . 14 3.2.2 Support for multi-attribute search indexes . 15 3.2.3 Search by proximity . 15 3.2.4 Search patterns with additional constraints . 16 3.2.5 Searching notes . 16 3.3 Richer Text Replace . 16 3.4 Richer Tracing . 17 3.5 Richer Selection and Insertion . 19 3.6 Commands and Scripting . 20 3.7 Compatibility with Other Systems . 20 3.8 Richer Static Assertions and Macro Expansion . 21 4 Conclusion and Future Work 22 List of Figures 1 Guy L Steele showing highlighted code . 3 2 Cartoon depiction of the program comprehension process . 4 3 Wire Marker - a browser plug-in for annotating web-pages . 5 4 iAnnotate - a program for annotating PDF and other formats . 5 5 Sample of Spectral rich text file . 8 6 Visual rendering of the rich text given in Figure 5 . 8 7 Annotated version of the text in Figure 5 . 9 8 Merge conflict markers displayed on Spectral . 10 9 Spectral editor views with highlighted salient symbols . 13 10 Source code annotated with hit counts . 19 Rich Text Programming : A Tool for Code Comprehension 1 Introduction Let us start by noting the following quotes from famous programmers: Let us change our traditional attitude to the construction of programs. Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. - Donald E Knuth, in Literate Programming [6] In the last 40 years we have written billions of lines of code that will keep programmers employed for trillions of man hours in the next few thou- sand years to clean up the mess we have made. All that stuff we wrote years ago, you know, these poor sods will be scratching their heads and going ”What the hell does this stuff do?” right? And it’s terrible - Joe Armstrong, in his talk titled ”The Mess We’re In” [3] Programs are written for people to read, and only incidentally for ma- chines to execute. - Harold Abelson, in Structure and Interpretation of Computer Programs [1] Management and mitigation of code complexity is crucial to the sustenance oflarge long-lived software products. This goal is approached from many directions, someof which are listed below: • Separation of concerns (e.g. modularisation, layering, abstraction, etc.) • Language imposed constraints (e.g. type safety, functional programming, vari- able immutability etc.) • Documentation formalisms (e.g. UML) • Shared vocabulary of design patterns, algorithms, and idioms • Coding standards • Code reviews Page 1 of 24 Copyright (C) 2015 Jayanta Majumder, Shikha Sarkar, Sambuddha Majumder Rich Text Programming : A Tool for Code Comprehension However diverse these directions and approaches might seem on the surface, deep down they have a central theme - that of making the code easier to understand. Ease of modification, maintenance, and extension follows as a result of ease of understand- ing. Programmers often talk about the notion of beautiful code, but any such subjec- tive beauty when not strongly correlated to the objective notionof cognitive ease ends up making the code hard to maintain. Knuth’s literate programming [6] idea approaches this objective by documenting the progression of the development in an order that is most conducive to human under- standing. A literate program is a combination of code and documentation that com- piles into machine executable code as well into a richly formatted text that may be published as a book or used as a reference. Many notable programs and books have been written using this approach (e.g [5], in which the authors note that the booknot only describes the implementation of lcc (a C compiler), it is the implementation. Literate programming, for all its beautiful outcomes, did not really catch on, perhaps due to short-term commercial pressures taking priority over long term maintainability in the software industry. Here we introduce an alternative approach that hassome aspects in common with literate programming, but can potentially be a better fit with mainstream programming practice because of its incremental approach - in that its adoption doesn’t need a big change in the practice, and the adoption level canvary continuously from zero to full-blown adoption. The approach iscalled rich program- ming (RP) - i.e. programming with rich-text. Here we use the term rich text in a broad sense in that it allows beautiful text formatting (using fonts, colours, underlines, high- lighting, hyper-links, etc.) along with multimedia (images, audio, video etc.). Rich text is more conducive to human perusal due to the availability of additional vi- sual cues and options of interactivity. So it is a common practice to have additional richer material describing the code - in which parts of the code is excerpted and pre- sented along with diagrams and multimedia. For example, the photo in figure 1is taken from a google tech-talk video, in which Guy L Steele is presenting some code, and note how he uses highlighting to emphasize some salient lines. Having made these observations, we did what any wannabe inventor would do- we asked ourselves a question. The question was - wouldn’t it be nice if the coding itself could generally be done in a rich text environment, where one could highlight, annotate, hyperlink, and so on to make the code easier to understand? or something on those lines. In exploring that question, we came up with a new kind of text editor that can make programming more fun and programs easier to read. We named it the Spec- tral Editor. It is a WYSWYG tool that allows you to edit rich text while automatically Page 2 of 24 Copyright (C) 2015 Jayanta Majumder, Shikha Sarkar, Sambuddha Majumder Rich Text Programming : A Tool for Code Comprehension Figure 1: Guy L Steele showing highlighted code maintaining the underlying plain-text representation. The central idea of this editor is a marriage between rich text and plain text formats which brings about the best of both worlds. It begets the maintainability merits of plain text (e.g. simplicity of auto- matic merging, concatenation, and version management) alongside the visual appeal of rich text (e.g. fonts, color, graphics, etc.). The editor is built around a file format that represents rich text in a way that preserves line-to-line correspondence with the plain text content. The rich text view would incorporate pictures, notes, audio, video etc. to enrich the programming and program comprehension experience, while the corresponding plain text source code is preserved all along with an intuitive mapping between the plain and the rich text. The video in [8] gives a quick tour of the basic features of spectral. This work arguably belongs in the body of literature on program comprehension. Readers looking for a broader survey on precursor work are advised to consult pub- lications made in the annual International Conference on Program Comprehension - ICPC. The papers published in that conference are behind pay-walls, but some pre- cursor works that could be found on public-access sites are [4], [2], [12] and [11]. Despite the substantial literature on program comprehension, its toolkit continues to be the (i) debugger, (ii) the profiler, and (iii) log files, driven by deep and preferably uninterrupted thinking, assisted by a pencil and scratchpad. Figure 2 illustrates this Page 3 of 24 Copyright (C) 2015 Jayanta Majumder, Shikha Sarkar, Sambuddha Majumder Rich Text Programming : A Tool for Code Comprehension Figure 2: Cartoon depiction of the program comprehension process activity in a light vein. The proposed rich text editor aims at augmenting thistoolkit, by allowing programmers to accumulate explanations, annotations, and diagrams on the code text to keep the additional information in context. Annotating digital documents is not new. In fact there are dozens of editors that allow annotation of popular document formats like Adobe PDF, MS Word Doc,Web pages etc. Figure 3 and 4 are two examples. Table 1 lists many more. However, none of the available annotation tools target program text. The proposed tool aims to ad- dress this gap, as elaborated in the following sections.