Ask HN: How to be productive with big existing code base

I have just started working with one of the client who have existing nodeJS code which they build in last 3 years.

Is there any guiding principle which is beneficial while working with existing code base?

What is your problem with the code base actually?

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
    >
    >
    >
  #+END_SRC
  ** includes
  #+NAME: includes
  #+BEGIN_SRC c
    ,#include  // [0]
  #+END_SRC
  ** structs
  #+NAME: structs
  #+BEGIN_SRC c
    // structs
  #+END_SRC
  ** functions
  #+NAME: functions
  #+BEGIN_SRC c :noweb yes
    >
    >
  #+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.

This.

I see myself in your words.

I dunno, I've seen quite a few piles of crap in my day as a SWE. The bar is not that high to do better.