Developers spend a lot of time and effort navigating code. I designed three tools for code editors to help with this: (1) Patchworks for navigating among your already opened code documents, (2) Yestercode for viewing previous versions of a code document, and (3) Wandercode for exploring code based on structural relationships. These tool designs were influenced by several empirical studies that I collaborated on regarding how developers seek information in code.
For each tool I evaluated them with a lab study (two for Patchworks) to measure their affect on things like task time, task success, cognitive load, developers' opinions of the tool, and qualitative observations of how people used them.
In the future I would really like to release them to the public as VS Code or Atom plugins.
I really love this research work - especially patchworks.
I think there is a huge amount of progress to be made when contemplating code from the "read and comprehend" use case rather than the edit use case.
Personally, I've taken to using command line syntax highlighters to render code to svg images, which I then open in a vector graphics program and mark up using a pen tablet (wacom). It reminds me of the days of printing out on a line printer and marking up with red pen offline. I just love it.
I haven't got time to read all this dissertation on an interesting topic at the moment, but I was surprised to find that the relevant work of the other great "Donald" (Knuth) is not mentioned. He called it 'literate programming'. Here's a reference: https://www-cs-faculty.stanford.edu/~knuth/lp.html
As DK puts it himself: "The main idea is to treat a program as a piece of literature, addressed to human beings rather than to a computer." I think code navigation would naturally fall out from this approach.
On the contrary, literate programming is heavily used in notebook environments (ipython, RMarkdown, Mathematica, etc) and in practice, code structured this way seems to implode once it gets above a few kloc. Narratives just don't seem to do a good job of hierarchy / modularization / separation of responsiblity, which is the key to programming in the large.
> literate programming is heavily used in notebook environments (ipython, RMarkdown, Mathematica, etc)
Do any of those actually implement Literate Programming as DK intended? As in "you can move the code around to wherever makes most sense for your narrative"? As best I know, almost all "literate programming" today is just the intermingling of code and text blocks (e.g. Docco et al) in the same order the code would have to be anyway (i.e. there's no TANGLE, only WEAVE.)
Note that literate programming and "modularization/separation" are both techniques for organizing your code, but they aren't mutually exclusive (though I understand the temptation to use only one). (Aside: what are now called "sections" in literate programming were originally called "modules".) (Disclaimer: I'm not sure I know what you mean by literate programming in notebook environments.)
Knuth wrote programs with pen/pencil on paper (https://news.ycombinator.com/item?id=10172924) (and from all I can tell, still does so), so Knuth-style Literate Programming's facilities for code "navigation" are all paper-based: at the back of the book there is an index to all the variables (where each variable is defined and all the places it's used), and (in the published books) there are even mini-indices on each two-page spread, restricted to just the variables that occur on those pages. The cross-references (like "See also sections 163 and 927" or "This code is used in section 4") are also meant to help you "navigate" to the respective pages.
In one of the "internals of TeX" videos, Knuth mentions how when he got to a particular section of the code, he had to move to a larger desk (yes, desk) so that everything could stay in sight. If you're comfortable with such a style of programming, paper gives you a lot of freedom: you can have a very large number of (literal) "tabs", cover parts of pages, make throwaway annotations while reading, etc.
Anyway, as far on-screen navigation goes, with pdfTeX there are hyperlinks: you can navigate from the mention of any section to its actual code, and backwards. (E.g. start at section 4 http://texdoc.net/texmf-dist/doc/generic/knuth/tex/tex.pdf#p... and go to one of the mentioned sections, and back from them to 4.) (It would be nice for there to be even more hyperlinks, but no one seems to have implemented them as Pascal isn't exactly popular these days.)
And to answer your question most concretely: the (recent) online version of the Literate-Programming book Physically Based Rendering: From Theory To Implementation has some innovative navigation aids IMO. (Random "page" / section from the book: http://www.pbr-book.org/3ed-2018/Camera_Models/Realistic_Cam...)
Interesting point, thank you! I have always liked the ideas behind literate programming. For my next piece of work on this I think I can use LP to really motivate the need for such tools.
Wow, for an IxD guy like me this certainly looks like it deserves a closer look! From a quick skim it seems like it hits the right balance of "objective" evaluation methods, and sensible discussion and interpretation of the results in a human-centric design context. Looking forward to follow the author's line of thinking in more detail later.
Is that code extension already available somewhere?
Sadly, Patchworks is not currently available. I implemented two versions: A C# standalone editor for Java and C# that is difficult to build at this point and a version built into the proprietary LabVIEW code editor.
If anyone would like to help with a VS Code or Atom plugin, let me know :)
That looks very useful!
All the more reason to keep evangelizing about an 80-chars maximum line lengths in code. It bothers me how these programmers that use their 4K / 16:9 monitors with a full-screen tab seem to think that obviously, everybody must be working like they do, right?
I think I'm already emulating that to some degree by tiling multiple windows on multiple desktops and switching between them. So yeah, might as well have the editor support it from the start.
The Wandercode interface on the other hand I can't find a quick replacement for. From a quick skim it seems like it hits a good balance of making navigation easier without putting so much information on the that it becomes noise. Really would like to try that out!
Tiling and window managers are exactly what inspired Patchworks!
It is possible that Wandercode may be released to the public in the near future. It is an Atom plugin in working state, it just needs some fixing up on how it generates the call graph to make the recommendations. Stay tuned!
I'm particularly interested in trying out Wandercode. What's a good way for me to follow its development?
Wandercode looks very similar to an idea I had for navigation while working on a task that was 100% code review and comprehension. I wanted similar graph displays for inheritance, and data flow through variables. I envisioned all of this displayed together in a large window, basically with multiple DAGs overlaid on each other in different colors. Now, seeing Wandercode, I imagine a handful of small, "localized" displays, focused on a selected function/class/variable. Any thoughts on that? Or are function calls more interesting for you?
Author here. This is my dissertation that I completed back in July. I'm happy to answer questions!
To summarize the dissertation a bit:
Developers spend a lot of time and effort navigating code. I designed three tools for code editors to help with this: (1) Patchworks for navigating among your already opened code documents, (2) Yestercode for viewing previous versions of a code document, and (3) Wandercode for exploring code based on structural relationships. These tool designs were influenced by several empirical studies that I collaborated on regarding how developers seek information in code.
For each tool I evaluated them with a lab study (two for Patchworks) to measure their affect on things like task time, task success, cognitive load, developers' opinions of the tool, and qualitative observations of how people used them.
In the future I would really like to release them to the public as VS Code or Atom plugins.
Thanks a lot for providing this summary.
I really love this research work - especially patchworks.
I think there is a huge amount of progress to be made when contemplating code from the "read and comprehend" use case rather than the edit use case.
Personally, I've taken to using command line syntax highlighters to render code to svg images, which I then open in a vector graphics program and mark up using a pen tablet (wacom). It reminds me of the days of printing out on a line printer and marking up with red pen offline. I just love it.
I haven't got time to read all this dissertation on an interesting topic at the moment, but I was surprised to find that the relevant work of the other great "Donald" (Knuth) is not mentioned. He called it 'literate programming'. Here's a reference: https://www-cs-faculty.stanford.edu/~knuth/lp.html
I’ve known literate programming only as a way to structure programs.
What code navigation features are part of literate programming and would be appropriate for inclusion in this dissertation?
As DK puts it himself: "The main idea is to treat a program as a piece of literature, addressed to human beings rather than to a computer." I think code navigation would naturally fall out from this approach.
On the contrary, literate programming is heavily used in notebook environments (ipython, RMarkdown, Mathematica, etc) and in practice, code structured this way seems to implode once it gets above a few kloc. Narratives just don't seem to do a good job of hierarchy / modularization / separation of responsiblity, which is the key to programming in the large.
> literate programming is heavily used in notebook environments (ipython, RMarkdown, Mathematica, etc)
Do any of those actually implement Literate Programming as DK intended? As in "you can move the code around to wherever makes most sense for your narrative"? As best I know, almost all "literate programming" today is just the intermingling of code and text blocks (e.g. Docco et al) in the same order the code would have to be anyway (i.e. there's no TANGLE, only WEAVE.)
Note that literate programming and "modularization/separation" are both techniques for organizing your code, but they aren't mutually exclusive (though I understand the temptation to use only one). (Aside: what are now called "sections" in literate programming were originally called "modules".) (Disclaimer: I'm not sure I know what you mean by literate programming in notebook environments.)
I think code navigation would naturally fall out from this approach.
That could be.
Are there any novel navigation approaches that have fallen out?
Knuth wrote programs with pen/pencil on paper (https://news.ycombinator.com/item?id=10172924) (and from all I can tell, still does so), so Knuth-style Literate Programming's facilities for code "navigation" are all paper-based: at the back of the book there is an index to all the variables (where each variable is defined and all the places it's used), and (in the published books) there are even mini-indices on each two-page spread, restricted to just the variables that occur on those pages. The cross-references (like "See also sections 163 and 927" or "This code is used in section 4") are also meant to help you "navigate" to the respective pages.
In one of the "internals of TeX" videos, Knuth mentions how when he got to a particular section of the code, he had to move to a larger desk (yes, desk) so that everything could stay in sight. If you're comfortable with such a style of programming, paper gives you a lot of freedom: you can have a very large number of (literal) "tabs", cover parts of pages, make throwaway annotations while reading, etc.
Anyway, as far on-screen navigation goes, with pdfTeX there are hyperlinks: you can navigate from the mention of any section to its actual code, and backwards. (E.g. start at section 4 http://texdoc.net/texmf-dist/doc/generic/knuth/tex/tex.pdf#p... and go to one of the mentioned sections, and back from them to 4.) (It would be nice for there to be even more hyperlinks, but no one seems to have implemented them as Pascal isn't exactly popular these days.)
And to answer your question most concretely: the (recent) online version of the Literate-Programming book Physically Based Rendering: From Theory To Implementation has some innovative navigation aids IMO. (Random "page" / section from the book: http://www.pbr-book.org/3ed-2018/Camera_Models/Realistic_Cam...)
Interesting point, thank you! I have always liked the ideas behind literate programming. For my next piece of work on this I think I can use LP to really motivate the need for such tools.
Wow, for an IxD guy like me this certainly looks like it deserves a closer look! From a quick skim it seems like it hits the right balance of "objective" evaluation methods, and sensible discussion and interpretation of the results in a human-centric design context. Looking forward to follow the author's line of thinking in more detail later.
Is that code extension already available somewhere?
Sadly, Patchworks is not currently available. I implemented two versions: A C# standalone editor for Java and C# that is difficult to build at this point and a version built into the proprietary LabVIEW code editor.
If anyone would like to help with a VS Code or Atom plugin, let me know :)
Here's a really nice video of the Patchworks Editor: https://www.youtube.com/watch?v=GwcxDZT3pXE
That looks very useful! All the more reason to keep evangelizing about an 80-chars maximum line lengths in code. It bothers me how these programmers that use their 4K / 16:9 monitors with a full-screen tab seem to think that obviously, everybody must be working like they do, right?
I mainly love it because it encourages refactoring
Two more videos summarizing my conference talks on Patchworks in 30 seconds each:
CHI'14: https://www.youtube.com/watch?v=tGkGjZI21Mw
CHI'17: https://www.youtube.com/watch?v=odkrnvfNfHU
I would love this in Visual Studio.
This is great stuff. I wish I have found this back when we started to develop https://type12.com editor for pair-program interviews.
The patch grid and ribbon in the Patchworks Editor this proposes are exactly what I didn’t know I needed
I think I'm already emulating that to some degree by tiling multiple windows on multiple desktops and switching between them. So yeah, might as well have the editor support it from the start.
The Wandercode interface on the other hand I can't find a quick replacement for. From a quick skim it seems like it hits a good balance of making navigation easier without putting so much information on the that it becomes noise. Really would like to try that out!
Tiling and window managers are exactly what inspired Patchworks!
It is possible that Wandercode may be released to the public in the near future. It is an Atom plugin in working state, it just needs some fixing up on how it generates the call graph to make the recommendations. Stay tuned!
I'm particularly interested in trying out Wandercode. What's a good way for me to follow its development?
Wandercode looks very similar to an idea I had for navigation while working on a task that was 100% code review and comprehension. I wanted similar graph displays for inheritance, and data flow through variables. I envisioned all of this displayed together in a large window, basically with multiple DAGs overlaid on each other in different colors. Now, seeing Wandercode, I imagine a handful of small, "localized" displays, focused on a selected function/class/variable. Any thoughts on that? Or are function calls more interesting for you?