Taking ASCII Drawings Seriously: How Programmers Diagram Code

Title of the Paper

Taking ASCII Drawings Seriously: How Programmers Diagram Code

Bibliographic Information

• Subject Area: Application and analysis of ASCII graphics in software development
• Keywords: programming, graphical representation, ASCII diagrams, software development, documentation tools, design space, open-source code, knowledge transfer

Research Background and Issues

• Problems and Challenges:

  • Most programming tools are text-centric, and programmers often use ASCII diagrams (text-based graphical representations) to visualize concepts. However, there is little academic research on these diagrams, and researchers lack a systematic understanding of why they are created, the contexts in which they are used, and the content they convey.
  • Current issues with code documentation include inconsistencies between documentation and code, complexity in updates, maintenance difficulties, and insufficient integration of visualization with text.

• Significance:

  • ASCII diagrams have practical applications throughout the software development lifecycle, including design, testing, code review, and knowledge transfer. A systematic understanding of these practices can improve future tools, enabling tighter integration of text and graphics.

• Research Motivation and Related Work:

  • In recent years, numerous studies have attempted to incorporate visualization into programming education, communication, and development tools, but most focus on specific types of diagrams (e.g., UML). There is limited research on how developers embed visualizations (such as ASCII diagrams) directly into code.
  • This study complements and extends Cherubini et al.'s research on the role of diagrams in software development by conducting a systematic analysis of the content and design of ASCII diagrams.

Solution

• Research Methods:

  • Conducted interviews with 9 authors of ASCII diagrams to address research questions regarding the characteristics, roles, and content of ASCII diagrams.
  • Collected 507 ASCII diagrams from 4 major open-source projects (Linux, Chromium, LLVM, TensorFlow) and performed a content analysis to develop a design space with seven dimensions.

• Innovations:

  • Combination of Interviews and Content Analysis: Conducted the first systematic analysis of ASCII diagrams as professional documentation tools.
  • Design Space Model: Defined seven dimensions to classify these diagrams, detailing their forms of expression and their relationship to code.

• Implementation Steps and Techniques:

  • Data Collection: Manually filtered 2,156 ASCII diagrams from code repositories based on annotation format features.
  • Coding and Analysis: Conducted thematic analysis of representative diagrams based on concepts, visualization forms, and relationships with code, summarizing classification dimensions.
  • Interviews: Discussed motivations for creating diagrams, design processes, and audience needs, summarizing five practical use cases for diagrams.

Research Findings

• Specific Results:

  1. Key Characteristics: ASCII diagrams exhibit dual characteristics of "text" and "visualization."
     • As text, they integrate seamlessly with code, facilitating operation, viewing, and collaboration.
     • As a visualization form, they better convey concepts that are difficult to describe clearly with code or text alone.
  2. Roles and Applications:
     • Re-express external information (results of offline sketches or reverse engineering).
     • Illustrate test cases.
     • Assist in code review and validation.
     • Provide documentation support for others or for the future self.
  3. Design Space:
     • Covers seven dimensions (concept, visual encoding, annotation, abstraction, omission, scope, reference), reflecting the diversity of content and forms in ASCII diagrams.
  4. Tool Design Insights: Offers suggestions for designing future tools that integrate text and visualization, such as supporting bidirectional editing (ASCII and vector graphics) and tighter linkage with code.

• Advantages:

  • Compared to existing tools (e.g., external documentation or advanced visualization tools), ASCII diagrams are more usable due to their embedded nature, allowing them to integrate seamlessly into existing software development workflows.
  • Low creation barrier and broad compatibility (suitable for any text editor, terminal, etc.).

• Experimental and Evaluation Results:

  • Analysis of 2,156 diagrams collected from 4 large open-source codebases revealed that, despite their simplicity, ASCII diagrams exhibit significant diversity in content and visual forms.
  • The design space effectively describes the composition and functionality of these diagrams, making it applicable for further research and tool design.

• Limitations and Future Directions:

  • Limitations:
    1. Only four open-source project samples were selected, which may not comprehensively cover all use cases.
    2. Data analysis was primarily conducted by researchers with computer science backgrounds, potentially limiting understanding of diagrams in other fields.
  • Future Directions:
    1. Develop tools that support richer media formats while maintaining broad compatibility.
    2. Explore interactive diagram editors compatible with large-scale programming tools.
    3. Develop automated tools leveraging natural language processing (e.g., large language models) to generate dynamic visualizations.