Hyperlinked, externalized source code documentation

Posted by Dave Jarvis on Programmers See other posts from Programmers or by Dave Jarvis
Published on 2013-09-19T03:52:29Z Indexed on 2013/10/27 4:14 UTC
Read the original article Hit count: 788

Why do we still embed natural language descriptions of source code (i.e., the reason why a line of code was written) within the source code, rather than as a separate document?

Given the expansive real-estate afforded to modern development environments (high-resolution monitors, dual-monitors, etc.), an IDE could provide semi-lock-step panels wherein source code is visually separated from -- but intrinsically linked to -- its corresponding comments. For example, developers could write source code comments in a hyper-linked markup language (linking to additional software requirements), which would simultaneously prevent documentation from cluttering the source code.

What shortcomings would inhibit such a software development mechanism?

A mock-up to help clarify the question:

Dual Editor Mockup

When the cursor is at a particular line in the source code (shown with a blue background, above), the documentation that corresponds to the line at the cursor is highlighted (i.e., distinguished from the other details). As noted in the question, the documentation would stay in lock-step with the source code as the cursor jumps through the source code. A hot-key could switch between "documentation mode" and "development mode".

Potential advantages include:

  • More source code and more documentation on the screen(s) at once
  • Ability to edit documentation independently of source code (regardless of language?)
  • Write documentation and source code in parallel without merge conflicts
  • Real-time hyperlinked documentation with superior text formatting
  • Quasi-real-time machine translation into different natural languages
  • Every line of code can be clearly linked to a task, business requirement, etc.
  • Documentation could automatically timestamp when each line of code was written (metrics)
  • Dynamic inclusion of architecture diagrams, images to explain relations, etc.
  • Single-source documentation (e.g., tag code snippets for user manual inclusion).

Note:

  • The documentation window can be collapsed
  • Workflow for viewing or comparing source files would not be affected
  • How the implementation happens is a detail; the documentation could be:
    • kept at the end of the source file;
    • split into two files by convention (filename.c, filename.c.doc); or
    • fully database-driven
  • By hyperlinked documentation, I mean linking to external sources (such as StackOverflow or Wikipedia) and internal documents (i.e., a wiki on a subdomain that could cross-reference business requirements documentation) and other source files (similar to JavaDocs).

Related thread: What's with the aversion to documentation in the industry?

© Programmers or respective owner

Related posts about development-process

Related posts about documentation