I'm in a long debugging task, I need to figure out where to hook up some extra functionality I need.

It's cumbersome work, and I've been debugging 2 whole days, and I'm on my third, but I work in multiple projects, and I'm returning to this after almost a week, and it's been hard to get back to the point I left at, and remember what was all this about, and what conclusions had I already arrived at.

How do you keep track of what you were doing/thinking in this kind of scenario where comments aren't actually the "right thing" to do? I do some comments in my testing code, plus some informative git/hg commit messages but that's kind of dirty.. written paper might be the answer...

  • I'd use ad-hoc spreadsheets for this, to keep track of different scenarios and their results. Commented Aug 29, 2011 at 16:16

3 Answers 3


for working on multiple, complex projects, regardless of whether they involve developing software, there's no substitute for writing things down.

I've used bug tracking software, spreadsheets, personal wikis, a self-developed database, and probably a dozen other methods I've forgotten over the years. Writing things down helps you recall not only what you did, but why you did it.

When it comes specifically to debugging, there's no reason you can check code-in-progress into your own personal version control system. You can clean it up before committing to the central source repository.

  • I write things down in notebooks, with a pen. I use one notebook per major project, and just jot down a quick line whenever I have a major thought. I find this works a lot better for me than typed notes do. Commented Aug 30, 2011 at 0:08
  • I have used virtually every low-tech and high-tech tool over decades. I've found that nothing works as well as being born with the right personality in the first place. Commented Aug 30, 2011 at 0:25
  • Probably true! But not particularly useful as advice. The main thing is for people to experiment and use what works best for them. I just wanted to mention that old-fashioned pen and paper is another option, in addition to the ones you already laid out in your reply. Commented Aug 30, 2011 at 1:12
  • No, that's turned out to be very useful. It keeps me from chasing every new idea for managing this kind of stuff, because none of them are going to work well for me. Commented Aug 30, 2011 at 11:23

I'm not sure for you, but for me Automatic Tests (Unit tests if possible) are a good way of discovering how the code works, and knowing that it doesn't work as expected.

Automatic Tests replaces debugging, changing a memory-backed developer-checked knowledge and verification, to a file-backed explicitely-checked one.

When coming back to your work later on, you will be at the same point after a few seconds executing your tests, instead of trying to retrieve your context from old memories and replaying a long debug sequence (these last two activities may require written communication anyway as memory might not suffice ; then Automatic Tests would have no overhead).

I know, some projects are not easily testable automatically. We use TDD to solve that problem, gaining also many other advantages ....

If you already write some automatic tests, the same tests you write automatically track what you are thinking and verifying, so you probably need nothing else. When you finally found your bug, you can keep your test sequence ... or refactor it ;-)

Edit after comment :

Testing how a library works ! I call that learning tests. Good that you do them :

  • they let you know exactly how the library is working.
  • they document that knowledge, for you later or for your team members
  • they may document the uses of that library, how it is used in your project (in my Aeronautics experiences, the company policy mandated that each external code is controlled, knowing precisely what features are used, and documenting what would be the effect on our software if the library would stop working !)
  • they serve as a non-regression test when you upgrade your library
  • it's not a "figuring out why doesn't it work as expected" debugging, but rather a "figuring out how is this library supposed to work" debugging, but thanks =) Commented Aug 29, 2011 at 18:28
  • wait.. yes.. you just hit me in the middle of my soul.. you're saying I don't need to go pdb;pdb.set_trace() all over the place anymore? can you link me to some kind of detail on this concept? Commented Aug 30, 2011 at 21:33

I setup a task with a reminder for two reasons:

  1. I need a prompt to return to the code.
  2. I can enter any notes or link to important documents, web pages, files, etc..

It's difficult to switch tasks if you're in constant fear of forgetting to back to that original bug. You do need to have some idea of when it is best to set the reminder. I also do this when leaving things over the weekend.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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