Hyperlinked, externalized source code documentation
- by Dave Jarvis
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:
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?
