Keeping a debugging journal

http://steverydz.com/2013/11/19/keeping-a-debugging-journal/

by steverydz • 13 years ago

58 26 13 years ago

Can you share your debugging journal? I have been thinking about keeping one, just to try see if there are patterns amongst the bugs I inadvertently write. There are indeed patterns and classes and categories of bugs, and I think that knowing them might prevent me from making the same (stupid) mistakes in the future.

steverydz2• 13 years ago

I just started it this afternoon but do intend to share it once it fills up a bit. I'll update the post when I do this.

lgas• 13 years ago

I started keeping a development journal when I found myself getting interrupted quite a bit more than usual. It turned out to be very helpful but somewhat tedious to maintain at the level I would have liked.

I had some ideas about how to write software to automate some of the tedium and how great it would be if there were a large scale system that many developers used for tracking their work. If this system existed it could compare and contrast techniques and approaches used by more productive developers and help guide less productive developers down the path to improved productivity.

It seems like it would also provide a pretty good automatic Stack Overflow like experience in terms of being able to search for error messages and find the steps others had taken to solve the same problems.

steverydz2• 13 years ago

That sounds like a great idea!

dpedu• 13 years ago

I like this idea. Would anyone find interest in a mini-site for programmers to talk about how they've squashed bugs? Sort of a mini-social network I suppose.

svckr• 13 years ago

I think that thing is called a quote bug-tracker unquote.

(ba dum tss)

kayzee• 13 years ago

StackOverflow contains a list of documented "bug fixes". and I bet most devs find their solutions on SO anyways.

I find this suggestion more valuable within a medium-large company. An old employer of mine had a "Trouble Call" reporting system where you submit a problem/solution and can search the DB later to help with repeat issues.

jewel• 13 years ago

I've found it to be really helpful to keep a project work log when working alone. Mine are very verbose and help the most at the time of writing, since it keeps me on task and solidifies ideas.

My friend does the same thing, here's what he wrote about it recently:

http://blag.cammunism.org/blog/2013/11/14/programmers-log/

etler• 13 years ago

Kinda sounds like a rubber duck debugging strategy.

ibash• 13 years ago

I do the same thing, but not just when working alone -- I just use a a text file in dropbox + vim.

For more complicated tasks I create check lists before hand (to make sure I cover the edge cases), and sometimes create "Testing:" check lists to make sure I also test all the edge cases. I also have free form text when I'm thinking about a problem, or when I get feedback about different things.

It's organized by day and is invaluable, with a simple search I can find out what I worked on any day -- really good for reflection and marking progress.

gjm11• 13 years ago

A particularly fine example of a bug journal (not exactly a debugging journal) is the one kept by Donald Knuth for his TeX typesetting system.

The list is at http://texdoc.net/texmf-dist/doc/generic/knuth/errata/errorl...; the fairly long and very interesting paper he wrote about it ("The Errors of TeX") unfortunately doesn't seem to be freely available, but there's a very short informal article (also by Knuth) about it at http://www.tug.org/TUGboat/tb10-4/tb26knut.pdf.

He classifies all the errors he's ever found (or had found by others) into 15 categories. (Here "errors" includes "enhancements found to be a good idea", just as in many issue-tracking systems.) In the full "Errors" paper he has much to say about each category, including concrete examples and more philosophical ruminations.

a_bonobo3• 13 years ago

You have a slight typo in that first link, HN interpreted the semicolon as part of the link, fixed:

http://texdoc.net/texmf-dist/doc/generic/knuth/errata/errorl...

taspeotis2• 13 years ago

This one stuck out for me:

    * Time sharing is very slow today, so I'm mostly reading technical reports while
        waiting three hours for compiler, editor, and loading routine.
    * I'm not counting this as debugging time!
    * (Came back in the evening.)

For reference, you can compile the Linux kernel in as few as eight minutes [1].

[1] http://askubuntu.com/a/244148

hobo_mark• 13 years ago

So much truth! I've been keeping one myself for the past ten months and it helps immensely when switching between projects all the time. I don't use a blog or evernote but a set of scripts I made, it's an excellent use case for Dropbox too.

jlas• 13 years ago

I've created my own MoinMoin (FOSS python wiki) instance primarily for keeping a development journal (http://wiki.juanl.org/DevLog).

I usually try to capture anything that I spend a significant amount of time figuring out.

The fact that it's a wiki makes it great for organizing other ideas too.

pjmorris• 13 years ago

I keep two text files open at all times: CurrentTasks.txt gets every new assignment and idea, sorted by priority order, most important stuff at the top.

Logbook<Year>.txt gets a date stamp every day, and collects the notes I take/leave myself as I go along, including any interesting command lines I won't remember later. I throw in any interesting error messages and other things I know I won't remember in detail.

Periodically, I'll garbage collect CurrentTasks and move the good intentions and other things I won't likely do over to the Logbook.

This is a corruption of David Allen's 'Getting Things Done' system, but it's worked well for me for years. I can't count the number of times the Logbook has acted as a ready reference for solving some obscure, occasional challenge.

thejosh• 13 years ago

Yep, and if you post it to say tumblr, or your blog then people searching for the same problem you have will also run across it.

Great way to help others, and keep the "Just Google It!" mantra alive.

rohamg• 13 years ago

Why not use GitHub? You can file and look up commit histories, write comments, track Issues/bug reports, collaborate with others.. all in one place.

If you want a public debugging journal for a private or self-hosted project, I think Evernote combined with http://postach.io would work beautifully.

leerodgers• 13 years ago

I think this is a helpful action in some cases as well. Especially on teams where its less of a bug and more of a FAQ. Various questions about an application that are common and where to look for the answers. Saves everyone time.

For actual bugs. A lot of times they are one off, but if it is say an issue with a configuration or deployment that could come up again I definetly see the value there.

fivesquare• 13 years ago

are there any sources we can go for explicitly for making some kind of debugging journal?

Keeping a debugging journal

Related Stories