What are the efficient ways to take "programmer" notes?

Question

I run many times into an issue where someone asked me about a bug or a feature I worked on. And it literally takes me a long time to recall it, usually by looking at Bugzila as well as my CVS reports. So I am trying to find a good way to take notes of what the things I have been working on, and looking for your suggestions. In fact, I usually take almost ZERO notes about what I have done, though I write notes when getting specification or some technical things.

I hear that some people create a new document for each issue or bug they are working on, and append configuration info, log output, my musings and things. I think it is good for weekly/monthly reports and such, plus helps remembering things you've worked on or similar bug you've fixed.

Please suggest how you take note?

Answer 1

The consensus seems to be that blogs or physical notebooks are the way to go. Barring those, you could use a wiki or an app like OneNote.

Please see this question: http://stackoverflow.com/questions/78756/what-do-you-use-to-keep-notes-as-a-developer

Answer 2

Desk + Crayola

Answer 3

A good source control system with good code comments and a good checkin comment policy works wonders.

Answer 4

Aside from the bug tracker or computerized notes, I always have a log book which I will use to jot down everything of some form of importance for each day. That way I can easily page back through it and find the particular date and see what I had written down there.

Paper + Pen is still a wonderful tool.

Answer 5

Blog it. Or Setup an internal Wiki for developer notes.

Answer 6

You want simplicity so you can get into very quickly. I use a text file and add it on the desktop and keep a standard name like NOTES, NOTES2 kind of in a README or TODO format with a date whenever you add new entries.

Anything will work so long as it is simple. If you start adding servers and wiki's and all of that stuff then you have overcomplicated what you want.

Answer 7

I have been using Moleskine notebooks for a good long time and whenever I move to something else (I have used OneNote, WikidPad, Tomboy.. etc) I always return back to my notebooks

Moleskine has all sizes not to mention at least 3 types of paper: plain, ruled, grid

http://www.moleskines.com/moleskine-softcover-xlarge-squared.html

Hope this helps

Answer 8

I'm a practical minimalist.

Notepad++ sits open on my right monitor every day. I add to it as I see fit but I always put notes into subversion when I commit changes. Things change quickly.

I used to use tiddlywiki a lot but Notepad++ works better for me and is stripped down to what I need - a place to type that I can search later. The thing I don't like about physical notebooks is that I have to be the search engine when looking for things in one.

That's how I do it.

Answer 9

I use cat >> ~/TODO, blog or write down in notebooks (physical).

Answer 10

People have suggested many ways of how to physically take down notes, but I think the approach is what is the most important.

Here at my job we work on custom software for many different companies, and at the end of each pay period we send them a timesheet which they must sign-off on for us to bill them. It just so happens that this Timesheet outlines all the work that a developer has done, and usually the structure is something like this.

Clock In - 8:00 AM

Analysis - 10:30 AM
Description of analysis work done.

Coding - 12:30 PM
Description of all coding work done.

The idea is to prove to the client that you weren't on StackOverflow all day when you were billing them. As a result you log all the coding, debugging, etc. that you do.

Even though I'm the first to admit that this process is a pain, I can't count the number of times I've gone back to look at my past timesheets to see how I resolved a problem that I'm encountering again, or to figure out where I left off on some project I haven't touched in a while. It's great.

Answer 11

Depending on your environment, you can make custom tags along the lines of //TODO: Additionally, you should set your source control system to refuse checkins without comments.

The absolute best way to document something over time, to let you know what you did and the next person know how to maintain it, is unit tests against all of your changes. Switch to an annotated view of the source for the unit tests and you have dates and times.

I also like one note, it's so effortless to drag and drop any format into and you don't worry about opening, saving, anything, just leave it running and it takes care of the details.

Answer 12

• have a blog, even if no one reads it. Write an article/howto/what-I-did on anything you figure out that you might want to remember months or years from now. Who knows, somebody else might find it useful too.
• use Trac or Github which provide a nice wiki for each project. In addition to your commit messages, you can keep notes and howto's in the wiki specific to a project. Obv. this helps in documentation and with the rest of your team
• for short-term notes, keep a notebook and a pencil handy. But if you are like me you will lose or misplace these things before long
• keep a TODO and CHANGELOG file in each project. Sometimes very hard to maintain, but I've had many times when those saved my a##
• if really important, get it tattooed on your arm like the guy in Memento.

I have a pretty bad memory and don't expect to remember anything after 2 weeks (often I do, but at the time you can't predict whether or not you will remember a given thing). So these are my adaptations and work pretty well.

Answer 13

My own system is:

• Index cards for immediate jotting down of things I need to remember or reference. (Almost all of these get thrown away by the end of the day.)
• OmniOutliner for personal notes
• OmniFocus for to-do lists
• Bug-tracking system comments for info about tracking down and fixing bugs
• Wiki for info to be shared with team
• Blog for stuff that might be of general interest to programmers everywhere

Typically, things start in OmniOutliner then get copied-and-pasted to other systems as appropriate.

My Macbook's Spotlight search is good at finding things, so I don't worry too much about organization.

Answer 14

I found the TodoList from this website: http://www.abstractspoon.com/ It's easy to use, requires no installation and has nice features.

And to handle futher notes, I'd recommend WikiPad, which lets you structure the information.

Answer 15

• Bug tracker for notes that concern the investigation of a specific issue. This can include test code, log outputs, updates of how you're narrowing things down and what you've ruled out. I try to assume that I will be run over by a bus, and somebody else will take over the bug tomorrow. They will have the bug tracker notes, any code in my current working directory on my PC, and can be assumed not to be able to read my handwriting. They want to be where I was by 10am at the latest. It should certainly include a complete description of the problem which caused the bug, and how it was fixed, for the historical record. This is what you'll go to when someone asks "what was that bugfix all about?". The ongoing detail is what you refer to if someone says, "I've seen a similar problem somewhere else, what should I be checking?"
• Same goes for new features and changes, using either bug tracker, request tracker, design document, or whatever you have.
• Comments in code for notes that explain why the implementation is how it is.
• Comments in documentation for notes that explain why the interface is how it is ("rationale").

I don't like keeping personal notes about my code just for me, even on a Wiki or blog that's theoretically public. Nobody else will ever find them when they need them, unless maybe (1) you have a really good internal search appliance, and (2) everyone is copiously blogging, such that other people expect there to be something worth searching for. If the notes relate to code, then they should be in the code, or its documentation, or at the very least in the bug tracker (which explains what was wrong with the previous code, whereas the comments explain what's right with the current version).

Notes like, "what did I have to do to get the IDE installed and working", sure, they go in a wiki or blog. Something public, or which your co-workers can see and search, but which is specific to you because you're the one most likely to want it.

If you're working on open source code, then blogging might be a better option, since anyone in the world might want to know about it, and will probably search the whole web for info. But I've never worked on a significant open source project.

Answer 16

I'm a big fan of Nick Cernis' Todoodlist.

Answer 17

I have found that TiddlyWiki is really handy. It's a self-contained wiki that I use to keep track of notes about all sorts of things -- from my personal todo to notes about the implementation of particular features. Combine that with Dropbox and it shows up on all of my systems.

Answer 18

Install a desktop search engine. Index text file notes, email and IM logs.

Also, I'll sometimes add a comment to the bug/feature request ticket with technical notes--clearly labeled as such so as not to confuse non-technical viewers.

Answer 19

While this isn't all that technical, I've become a big fan of the Hipster PDA.

(In short: a stack of 3x5 cards and a binder clip. It's actually quite useful.)