What are the efficient ways to take "programmer" notes? [closed]

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?

Acetanilide

we have wiki too, but do you enter all the information into wiki in regard to your bugs? How do you search it? – Acetanilide

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: https://stackoverflow.com/questions/78756/what-do-you-use-to-keep-notes-as-a-developer

Ginter

OneNote or Evernote, depending if you'd rather have handwriting recognition (OneNote) or universal sync (Evernote on PC/Mac/iPhone/etc.). – Raouf

Answer 2

Desk + Crayola

Elbertina

The Kindergarten version of my Paper + Pen! – Orosco

The brilliant bit about this is that the crayon doubles as food if you get hungry. – Carlitacarlo

Answer 3

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

Vane

That's a good answer, pun's intended :-) – Holomorphic

Answer 4

• 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.

Trilateral

Answer 5

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.

Dermatophyte

Same here, I keep a brief changelog/notes/todo list in notepad++ for each project I work on. – Tram

Answer 6

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.

Sphenoid

Answer 7

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

Yield

Answer 8

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.

Jablonski

Text files can also be easily searched by powerful tools like grep. They're even relatively future proof: Your average ASCII-based text file can be read by a computer from 1989 and will almost certainly be readable by a computer in 2029. – Cramp

Answer 9

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.

Cytology

Answer 10

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.

Longlongan

Answer 11

Another way to take notes is using a Mind Map. It takes a bit to get the hang of it, but I've found these to be incredibly valuable in organizing my thoughts on various subjects, including programming tasks. I even patched one of the tools to transform my mindmap directly into nested lists pasteable into a Jira comment :) Makes code read notes and design/estimate notes very easy to construct and change.

A couple of tools that work well for mind mapping:

• XMind
• vym (View your Mind)

Cytology

Answer 12

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.

Orosco

Answer 13

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

Nonsense

Answer 14

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

Gibby

Answer 15

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.

Rufford

Answer 16

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.

Spandau

Answer 17

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.

Sophister

Answer 18

• 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.

Earthen

Answer 19

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

Uniat

Answer 20

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.)

Weary

Answer 21

I Like jira Its very well designed ,but not free

http://www.atlassian.com/software/jira

Costly