Ask HN: How to be productive with big existing code base
Document everything as you explore it. I&#x27;m an advocate for literate programming but accept it&#x27;s not going to be accepted by most organizations. So I use it as a personal tool.<p>Tools: emacs, org mode, org babel.<p>Create a parallel directory structure, hypothetical project:<p><pre><code>  .&#x2F;src
  .&#x2F;project&#x2F;src&#x2F;main.js
  .&#x2F;project&#x2F;src&#x2F;some-file.js
</code></pre>
Create a new directory structure with one org file per source file and one index org file:<p><pre><code>  .&#x2F;project-org&#x2F;src&#x2F;main.org
  .&#x2F;project-org&#x2F;src&#x2F;some-file.org
  .&#x2F;project-org&#x2F;index.org
</code></pre>
(You can organize it differently, this has worked for me.)<p><i>index.org</i> will be a simple tree view of the folder hierarchy:<p><pre><code>  * Project Name
  Description
  ** Source Files
  *** src
  **** [file:src&#x2F;main.org]
  **** [file:src&#x2F;some-file.org]
</code></pre>
You may add in some notes about the general purpose of each of those files.<p><i>main.org</i> copy the entire code into the main.org file like:<p><pre><code>  * main.js
  #+BEGIN_SRC js
  &#x2F;&#x2F; all the code from main.js
  #+END_SRC
  * [[file:..&#x2F;index.org][Project Root]]
</code></pre>
Start splitting the contents of <i>main.js</i> into separate snippets, I don&#x27;t know Javascript very well so let me make some quick C example:<p><pre><code>  * main.c
  #+BEGIN_SRC c :noweb yes :tangle yes
    &lt;&lt;includes&gt;&gt;
    &lt;&lt;structs&gt;&gt;
    &lt;&lt;functions&gt;&gt;
  #+END_SRC
  ** includes
  #+NAME: includes
  #+BEGIN_SRC c
    ,#include &lt;stdio.h&gt; &#x2F;&#x2F; [0]
  #+END_SRC
  ** structs
  #+NAME: structs
  #+BEGIN_SRC c
    &#x2F;&#x2F; structs
  #+END_SRC
  ** functions
  #+NAME: functions
  #+BEGIN_SRC c :noweb yes
    &lt;&lt;some-func&gt;&gt;
    &lt;&lt;main&gt;&gt;
  #+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
</code></pre>
As you go through this you can make cross-references to other files and functions&#x2F;structures. Eventually you&#x27;ll find a smallest reasonable unit. A long, but clear, function doesn&#x27;t need to be dissected. But a short, complex one, may end up with each line broken out and analyzed.<p>I don&#x27;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 (&quot;How does X happen?&quot;). 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.<p>[0] The comma is inserted by org babel to distinguish from it&#x27;s on #-prefixed content.