4 ms·
Document everything as you explore it. I'm an advocate for literate programming but accept it's not going to be accepted by most organizations. So I use it as a
by Jtsummers 8y ago
Document everything as you explore it. I'm an advocate for literate programming but accept it's not going to be accepted by most organizations. So I use it as a personal tool.
Tools: emacs, org mode, org babel.
Create a parallel directory structure, hypothetical project:
./src
./project/src/main.js
./project/src/some-file.js
Create a new directory structure with one org file per source file and one index org file:
./project-org/src/main.org
./project-org/src/some-file.org
./project-org/index.org
(You can organize it differently, this has worked for me.)
index.org will be a simple tree view of the folder hierarchy:
* Project Name
Description
** Source Files
*** src
**** [file:src/main.org]
**** [file:src/some-file.org]
You may add in some notes about the general purpose of each of those files.
main.org copy the entire code into the main.org file like:
* main.js
#+BEGIN_SRC js
// all the code from main.js
#+END_SRC
* [[file:../index.org][Project Root]]
Start splitting the contents of main.js into separate snippets, I don't know Javascript very well so let me make some quick C example:
* main.c
#+BEGIN_SRC c :noweb yes :tangle yes
<<includes>>
<<structs>>
<<functions>>
#+END_SRC
** includes
#+NAME: includes
#+BEGIN_SRC c
,#include <stdio.h> // [0]
#+END_SRC
** structs
#+NAME: structs
#+BEGIN_SRC c
// structs
#+END_SRC
** functions
#+NAME: functions
#+BEGIN_SRC c :noweb yes
<<some-func>>
<<main>>
#+END_SRC
*** main
#+NAME: functions
#+BEGIN_SRC c
int main (...) {...}
#+END_SRC
*** some_func
This function will initialize a block of memory
to be used as a shared buffer between two processes.
#+NAME: some_func
#+BEGIN_SRC c
void some_func (...) {...}
#+END_SRC
As you go through this you can make cross-references to other files and functions/structures. Eventually you'll find a smallest reasonable unit. A long, but clear, function doesn't need to be dissected. But a short, complex one, may end up with each line broken out and analyzed.
I don't just import a massive code base and do this in one go. Instead I import parts of it and break down all the related files to a particular topic ("How does X happen?"). I trace it from start to end, and then repeat with the next question. Good, modular code makes this much, much easier. The more tightly coupled, the harder it is to understand no matter the method.
[0] The comma is inserted by org babel to distinguish from it's on #-prefixed content.
- dpflan 8y agoI like this and have considered this approach using a git branch for annotations (although specific to using git, not familiar with other version control software). Have you done the git branch (or equivalent) approach?
- Jtsummers 8y agoI have made a new repo or a branch. Yes, but I typically keep it to myself and generate reports for others (if used at work). EDIT: I was on mobile earlier, so extending my thoughts. I typically make a new branch or repository but keep it on my own machine. I've gotten zero interest from colleagues in collaborating on this sort of thing, but they usually like the output. Org mode (my tool of choice, but not the only one) creates decent HTML output (you may want to play around with your own CSS or color schemes for the code blocks). So what I've done when we on-boarded a new project was to start doing this for certain critical sections that were under-documented. I then generated HTML output as a sort of white paper, and a PowerPoint deck that walked through the structure and control flow (would be best if I used flowcharts, but usually this is just text). If we had good development machines at work, I'd definitely do the above with PlantUML or something similar to do text-based diagrams. Org will produce and embed images in the HTML output. This would make the flow for producing documentation much easier, I disliked trying to embed flowcharts created in Visio (tool available at work) into the HTML. I had to generate them, export to an image, link the image in org, and then keep it up to date manually. For a few charts it's not bad, but if you make a lot it's tedious to switch between tools and correctly export the image. ===== For non-work stuff, I try to use literate programming from the start, but it's always solo projects so there's no "selling" this method. If I were collaborating with others, I'd have to reconsider the method. Leo has (from what I've read) an effective literate->code->literate story (that is, edit the code and the changes show back up in the literate format). Org mode can do that, but I haven't explored it. I'd really want that if I was to pursue literate programming in a collaborative environment (so that those uninterested in my method could still contribute).
- dpflan 8y agoAmazing, thank you for following up! [I had constructed a reply to your comment while it was being edited so when I posted the comment was much longer and had provided more than enough detail! Revised this comment accordingly]