Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Whenever we start reading a big project source code it's often necessary to note down the calling chains and notes that reason why a specific code pattern was chosen, for example. I found primitive tools like A4 sheets lack the cut and paste or find capabilities. Consider working with a very simple editor like command line ones (such as vim/emacs or nano), or other lite IDEs like Geany. What are your methods to take notes to help you track the code folds and- ummm- mazes?

share|improve this question

closed as primarily opinion-based by gnat, maple_shaft Oct 23 '14 at 11:32

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise. If this question can be reworded to fit the rules in the help center, please edit the question.

If your language and IDE support it (like C# and Visual Studio Do) use the IDE to generate a class diagram. I find that seeing the overall structure makes everything easier to understand. –  Evan Plaice Mar 25 '11 at 14:07
In fact class diagrams doesn't help in cases when methods/properties names is less descriptive or lacking proper comments, so tracking code is harder then. I work under a Linux workstation with remote access to Linux servers. –  rahmanisback Mar 25 '11 at 14:14
@rahmanisback I usually structure code in a manner that methods/properties usually tell enough about what they do to make sense. I also document everything that's public/internal with detailed comments so the info shows up on the auto complete. Of course, I work mostly on API's not applications. From monodevelop.com/Developers/Tasks/General/Class_Diagram_View planning for class diagrams is in the works for monodevelop is in the works but not implemented yet. I wrote a comment (instead of an answer) because 'class diagram' views usually require a pretty advanced IDE. –  Evan Plaice Mar 25 '11 at 14:49
@Evan: Occasionally you encounter a large project you did not participate in writing. But for what you write you can make it self describing, and this is what "they" should have done. –  rahmanisback Mar 25 '11 at 15:37
@rahmanisback I haven't really worked on any of the 'big' projects yet so I guess I haven't seen how bad it could be. :) –  Evan Plaice Mar 25 '11 at 16:08

7 Answers 7

up vote 3 down vote accepted

For large projects I find that a mindmapping tool like Free Mind is a HUGE help. The ability to collapse and expand the different areas make it much easier to get an overview of what's happening and then be able to drill down to be as specific as you like.

share|improve this answer
+1 Nice choice. I'd also add that knowing the keyboard shortcuts is essential to working really fast in FM. If you want me to edit them into your answer just hit me up with a response. –  Evan Plaice Apr 6 '11 at 0:15
@Evan Plaice - Knock yourself out, edit or leave them as a comment whatever strikes your fancy –  DKnight Apr 6 '11 at 15:58
Cool, done... –  Evan Plaice Apr 7 '11 at 23:52

My method is simple, write it down, draw diagrams. The reason why I prefer this method is because it helps me learn the code faster. You accelerate learning when you write things down. Remember, typing does not have the same effect as writing it down by hand.

share|improve this answer
1+ Sure, you can't ignore primitive methods when stuck with technology problems. the author. –  rahmanisback Mar 25 '11 at 16:04
The studies showing that writing things down improves learning applied to people studying and listening to lectures. We guess the reason why it's better than typing is because when writing you are forced to listen, digest and summarize what they are saying. It's not as simple as saying "writing is better than typing", and possibly won't make much of a difference in this case. Having that I agree that drawing diagrams will help, because hand drawing means you can concentrate on the diagram, not on the software. –  LachlanB Oct 23 '14 at 5:41

Best thing I find is to use an application dedicated to note taking. My favourite is Evernote.

For things that may need to be shared among teams, a wiki is useful.

As a side note, taking notes is not just specific to following paths through the code. As a developer you should usually be taking notes daily on any number of things, from common commands to context and background on bugs or tasks, even just what you plan to do for the day. It's important and it's worth spending time finding an app/tool that suits your needs.

share|improve this answer
I used tomboy for long to create notes. But super long methods body and long loops are the problem, they need connector lines and a dirty sheet to be of any help. The problem with Evernote is they don't have a download for Linux –  rahmanisback Mar 25 '11 at 16:08
@rahmanisback there is an unofficial Evernote client for linux called Nevernote. –  Alb Mar 25 '11 at 16:20

I use a pen and a sheet (or multiple sheets) of paper. If there's something I really want to preserve for future reference, I type up my notes or use a diagramming tool (Dia). I've been known to print man pages and file the hard copy for things like C string formatting.

That said, I'm usually working alone, so teaming is not a big part of what I do.

share|improve this answer
1+ yeah true but, don't tell anyone, my handwritten text is unreadable by me sometimes –  rahmanisback Mar 25 '11 at 16:10

I often take notes while trying to understand other people's code, especially when I don't want to alter the source code itself in any way. At the moment, I keep my notes in a text file, but it's really cumbersome to continually flip between application windows, copying, pasting, and searching for identifier names, and relying on the same name appearing in multiple places to relate different notes to one another.

I'd love it if my code editor could help me with this. Just the ability to link a bit of text to any given function/method/variable/class name and store it in my project file would be a tremendous help. Bonus points if it could show me not only the note for the item I'm inspecting but also any other notes that mention it by name.

It seems others want this, too.

Maybe I'll write a Geany plugin for it one day

share|improve this answer
That would be great, why not starting a github repo for this Geany plugin? Let me know. –  rahmanisback Nov 5 '14 at 16:37
Heh... I don't have much free time, but if I ever have it in mind when some time comes up, I'll consider it. –  user153809 Nov 5 '14 at 18:15

Personally I like to leave the documentation of call-chains and the like to other programs (for example Doxygen springs to mind). What is of more interest is the common patterns and idioms used in the code. When working on open source projects it pays to pay attention to these as cooperation is easier when everyone is understands the same concepts.

share|improve this answer
if only all methods/properties are well named/commented out –  rahmanisback Mar 25 '11 at 16:15
doxygen is pretty good at outlining structure even if commenting is limited. It doesn't hurt to have more comments of course! –  stsquad Mar 28 '11 at 11:48

I just drop down into the debugger and see what the code is doing as it is executing a specific example. I get a much better understanding of what the code is doing and it also ends up being much easier to track down what I need to modify because there can be hundreds of files that are completely irrelevant for the use cases I have in mind. In general reading the source code and taking notes is almost never what you want to do.

share|improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.