I still don't know why we haven't stolen the Photoshop layers paradigm and applied it to code
I should be able to toggle a shallow layer and deep layer all from a single 'file'
So the you'd be able to have architectural notes in the deep layer etc.
In many ways our tools are stuck in time.
The normal unit of editing work in original Forth was a 1024 byte "page" called a SCREEN. You would write your code in an editor that arranged it as 16 lines of 64 characters. At the touch of a key (usually), you could swap to the shadow screen which would have the documentation on it. By convention, shadow screen comments were placed on the same line as the code they were remarking on, so everything was usually co-located.
By abusing autorepeat, it was even possible to "flicker" the code and documentation to see both at once.
Something like CWEB or org-mode permits interleaving code with comments, but it's one dimensional and breaks your flow when editing.
I started playing with it a while back in terms of how you'd structure it and what I came up with was something like
foo.cs
foo.shallow
foo.deep
If I ever get the time I'd like to implement a rough prototype in intellij.