When I first a codebase, I frequently take notes about it, as this SO answer suggests.

If some code chunk is small enough, I copy-paste to Word, print it out, and make hand-written annotation. If the code is long, I write down the line number and my comments about that line of code.

This process works, but is woefully inefficient. First, everything is handwritten and tends to get lost over time. Second, I constantly to have go between my notebook and the codebase, looking up the code that the line number refers to.

Is there any better tool of methods of taking notes about a codebase? In my ideal world I should be able to add comments similar to comments in a Github pull request. But I'm also open to other methods.

  • @gnat the tools listed there are great tools, but require me to push a change to the codebase. I'm looking for tactics that aid me in learning a codebase. The first is like sending editorial suggestions to a textbook author. the second is like scribbling my own notes on the book's margin. – Heisenberg Oct 3 '18 at 22:37
  • 2
    I see no conceptual difference. If it is critical for you to keep original codebase as is, you just make its copy or branch and push into there and that would be the only (insignificant) difference, the rest will be exactly the same – gnat Oct 3 '18 at 22:46
  • 2
    Once you start moving into code bases that are larger than a few thousand lines your entire idea of taking notes in the code and using those to remember what it all does is going out the window anyway. Better to take notes at a far higher level than specific lines of code or even specific code files. – jwenting Oct 4 '18 at 7:28