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.

I was working on a project three months back, and then suddenly another urgent project appeared and I was asked to shift my attention.

Starting tomorrow, I'll be heading back to the old project. I realize that I do not remember what exactly I was doing. I don't know where to begin.

How can I document a project such that anytime I look back it shouldn't take me more than a few minutes to get going from wherever I left. Are there best practices?

share|improve this question
94  
comments and commit messages, there's a reason people tell you to leave them –  ratchet freak Jul 22 at 12:04
4  
Doesn't this really depend on how you were tracking the project in the first place? Should we assume you were doing everything from memory and no other documentation? –  JeffO Jul 22 at 12:54
4  
@ratchetfreak I was about to say "That's only useful for developers" until I realized that you can apply the same principle to anything. Most document repositories have a notes section or a description; deliverables over email have message bodies (often ignored). Documents can have tracked changes and annotations. There's a whole ecosystem of comments and commit messages in the PM world too! </epiphany> –  corsiKa Jul 22 at 14:57
5  
I use version control system to remind me what I did last time, and a bug tracker to find out what still need to be done. –  Lie Ryan Jul 22 at 15:15
2  
Oh yeah, once after a three month break from work, I was asked on a job interview to describe my last project. I did it, but when they asked for details, I could not for the life of me remember them. They turned me down because apparently I'm a phony if I can't remember that. This happened about 15 years ago, but I still remember it. –  zespri Jul 23 at 0:50

14 Answers 14

up vote 35 down vote accepted

I just wanted to contribute some advice which is not going to be useful in your current situation, but you can start implementing it now to help in the future.

Of course there are the obvious candidates such as todo lists and issue logs; looking at the recently added issues should give you a clue as to what you were doing when you were pulled off the project.

On previous projects I have worked on, people were expected to keep a project log as part of the quality management process. The contents were not very clearly specified, but the idea was to keep a daily log of things related to the project that may be useful for continued work in the future or for review activities on completion; for example:

  • Observations about the quality of the project

    this code can use some refactoring

    did a quick implementation to get this to work but ABC would be better.

  • Todo items / issues that you would not want to formally record in an issue tracker

    "should make this method work for x < 0 but that's currently out of scope.

  • Design decisions - especially non-trivial ones.

    Our standard sort function performs a quick sort, but that does not preserve the order of items equal under the sorting condition, which we need here.

    The obvious algorithm would be ABC but that fails here because x could be negative so we need the generalized form (Wikipedia link).

  • Problems encountered and how you solved them. A very important one, in my personal opinion: whenever you run into a problem note it in the log.

    Checked out the code but it gave error XYZ0123, turns out I first had to upgrade component C to version 1.2 or higher.

The latter two points are very important. I've often encountered a similar situation or problem - sometimes in a completely different project - and thought "hmm, I remember spending a day on this, but what was the solution again?"

When you come back to a project after a while, reading back the project log (whether it's your own or the latest developer's) should put you back into the flow that you had when you left, and warn you of some of the traps that you may otherwise fall into again.

share|improve this answer

To-do lists are magic. Generally you need to keep an active to-do list for each project and even while you're busy programming, if you think of something that has to be done and you can't do it immediately, then it goes on the list. Keep this list in a well-known place, either in a spreadsheet or text file in the project folder electronically, or in your paper logbook.

Also, whenever you leave the project for overnight (or over the weekend), take a post-it note and write the next thing you were going to do on the note, and stick it to the monitor. That makes it more likely you'll get back into it quickly the next morning.

Edit:

I should mention that to-do lists (specifically prioritized to-do lists segregated by venue and project) are a key part of the Getting Things Done book, which I found highly influential.

share|improve this answer
22  
And if you are working on an agile project with small tasks, the backlog should be your primary to-do list for that project. –  Bart van Ingen Schenau Jul 22 at 12:11
1  
I've recently started doing what you mention in the last paragraph and it's massively helped me get going in the morning. –  Tom Hart Jul 22 at 12:53
5  
Indeed. Always park downhill. It's a matter of habit. I never leave a codebase without making a note for myself in the code or in my todo list on what to do next. I also make sure that everything I know I still have to do is in a todo either in the source (I use the TODO: convention in comments which my IDE can detect and present as a list), or in my separate todo list (I have just the one for all projects, but it is categorized and prioritized). –  Joeri Sebrechts Jul 22 at 13:20
3  
TODOs in the code are excellent, but you have to be diligent about putting them there, even for teeny little things. Having a todo target in your makefile that dumps them out is also useful. –  Blrfl Jul 22 at 13:29
4  
trello.com is a life saver. Even for those Monday Monring team meetings where I struggle to remember what I did last week and what I should be working on this week. Its also free. –  FooBar Jul 22 at 14:57

What to do now?

Now, from tomorrow I'll be heading back to my old project and I realize that I do not remember what exactly was I doing and where to start!

My guess is you have not done any of the next section. So looking up a todo list won't work.

  1. Block a period of time. Put this on your calendar and spend time reviewing the project. This might be reviewing documentation, code, requirements, etc.
  2. Accept it will take a while to get back up to speed. Make sure all those involved realize this. Make sure you realize this.
  3. Start with a small task. Rebuild your confidence some by doing something small. If you have a list of new items, work through smaller ones first. This not only rebuilds your confidence but also helps reacquaint yourself with the project.

How to make this better for yourself in future?

I wish to know how to document the project such that anytime I look back it shouldn't take me more than a few minutes to get going from wherever I left!

First, you need to have a system for keeping track of your todos. Do you have such a system now? How do you manage your current projectwork?

I could get hit by a bus tomorrow and my team would have a good idea of well over 90% of my action items. This is because I have a cohesive system for documenting my:

  • Immediate todos (<1 week items)
  • "Nice to have" todos
  • Milestones and macro todos (where specifics aren't meaningful)
  • Requirements/meeting notes

Plus, I use a VCS and comment my code where appropriate.

This works for me and my team since I am the primary developer. You can use some sort of issue tracking system for a team. Or a backlog when working with Agile. There are a ton of options. If you are really interested in this, read up on Getting Things Done or other relevant task management methodologies, which exist nearly precisely because of what you describe.

What's the point?

The specifics of the system are less relevant than that it is cohesive system and you use it. And that you use it. And use it. This is important. More important than a nice perfect system you don't use. Don't do "well most of my work is here, but some is in my head" or you'll hate yourself going back on a project.

Also, make sure your comments explain "why" rather than just the "what" for code. It's a lot easier to read "this is to fix a bug with IE8" and recall what the code does than a comment simply explaining the technical details.

share|improve this answer
    
@TheIndependentAquarius no problem, glad it was helpful. That situation can be overwhelming. –  enderland Jul 22 at 21:05
3  
+1 for emphasising to explain "why" in comments. –  ClickRick Jul 23 at 0:55
    
Why exactly was my "thanks" comment removed? This is ridiculous! –  TheIndependentAquarius Jul 23 at 5:21
    
@TheIndependentAquarius likely because generally comments are intended to be more or less post-its/stickies. The way Stack Exchange has things setup to say, "this answer was great" is either upvoting or accepting an answer. Comments here are not necessarily intended to last. –  enderland Jul 23 at 13:55
    
A much more streamlined version of this "to-do" list is to utilize an issue-tracking system. There are many free systems available, and many free Git providers have such a system built in to their service (see: GitHub). –  BTownTKD Jul 23 at 14:19

In my opinion, there are two parts to "resuming" a code project:

  1. Determining where you left off
  2. Remembering what left you have to do

This is one of those things that, I think, if you are doing version control the right way it'll be your "other brain".

Where did you leave off? As long as your are committing code frequently, look at your last changeset. It'll most likely jog something in your mind. If not, look at the past few, starting with the oldest and replaying commits.

As for what left you have to do, a backlog should serve that purpose (or a to-do list, or whatever you want to name it. Basically items for the future).

I am not a full-time software developer. I'm a programmer that hacks on the nights and weekends. Because of this, when work or other non-programming things take higher priority, sometimes I can go days and weeks without even pulling up my code with a glance. The above has proven to be quite effective.

share|improve this answer

This is not intended to be a complete answer—there are already several very good ones mentioning important things like how to use your VCS and your project management software—but rather an addendum adding a few points I did not see in any others, which I find to be very helpful, and which I hope other people might find helpful as well.

1. No task is too soon or too small to write down

People usually make TODO lists for things that they plan to do in the future, but since programming requires concentration, and since we can be interrupted at any time, I've found it helpful to write down even what I'm doing right now, or what I'm about to start in a matter of seconds. You may feel you're in the zone and you couldn't possibly forget the solution that just hit you in that aha moment, but when your co-worker drops by your cube to show you a picture of his infected toe, and you are only able to finally get rid of him by starting to gnaw on your own arm, you may wish you had written down a quick note, even if only on a Post-It™ note.

Of course some other more persistent medium might be better (I'm particularly fond of OmniFocus), but the point is to at least have it somewhere, even if you'll finish in 20 minutes and then throw the Post-It™ away. Although you may discover that that information becomes useful, to put on time sheets or invoices to the client, or when your boss/client asks you what you've been working on and you can't remember. If you drop all of these notes in a box or drawer or folder, then when a big interruption hits—an interrupting project—then you can glance through them and remember a lot of the things you did to get your code to the point where you find it when you return to the project.

2. Use a whiteboard at your desk to capture big-picture ideas

I have a 3" x 4" whiteboard next to my desk, so when I start a project I can brainstorm the solutions to all the problems I perceive in a project. It could be architectural diagrams, use cases, lists of risks and obstacles, or anything that seems relevant to you.

Some more formalized approaches require you to generate diagrams and use cases and so forth as "deliverables" in some paper or electronic format, but I find that that can create a lot of extra work, and just become a series of sub-projects that end up being divorced from the actual purpose of the main project, and just part of a formalized process that you have to do but that no one pays much attention to. A whiteboard is the simplest thing that actually works, at least in my experience. It is as persistent as you want (with a camera) and most importantly allows you to get your ideas down immediately.

I think better with a pen in my hand, so dumping my thoughts onto a white surface comes naturally to me, but if you don't find that to be the case for you, here are some questions that may help you decide what is relevant:

  • If I were the lead developer, about to go on a honeymoon for 3 months while other developers completed the project, what general direction would I want to give them? What ideas would I want to make sure they knew about, or approaches would I want to ensure they took? What libraries or other helpful solutions would I want to be sure they were aware of?
  • If this project were my million-dollar idea that I knew would ensure my future financial independence, but I was scheduled for a critical surgery that would incapacitate me for 3 months, what would I want my future self to have, to ensure successful completion of the project?

(When I first scribble ideas down, I only worry about them making sense to my present self. Once they are down I can look more critically at them and make changes to ensure they make sense to my future self or to others. Worrying too much about communicating to others as you write them down initially can lead to writers' block—a mind clogged by competing goals. Get it down first; worry about clarity later.)

I recommend you spend the money to buy a decent whiteboard, at least 3" x 4", and hang it up in the space where you normally work. There are many advantages of a physical whiteboard over any virtual system.

  • It is large. By taking up a lot of space it makes its presence felt, and the plans on it feel like they are a part of you workspace, helping to point you in the right direction all the time.
  • It is there persistently: you don't have launch a certain app or web site to access it, and you won't risk forgetting how to get to it, or forgetting that it's there.
  • It is immediately accessible when you have an idea that you want to think through.

You lose many of the benefits if you just use a whiteboard in a meeting room, and then take a snapshot with your phone. If you make money by programming, it's well worth the cost of a decent whiteboard.

If you have another project interrupt the one that has filled up your whiteboard, you may need to resort to the snapshot on your phone, but at least you'll have that in 3 months when the "urgent" project is finished and you have to return to the other one. If you want to recreate it on your whiteboard then, it would probably only take 15 minutes, and you may find you can improve it a lot in the process, which makes that small investment of time very worthwhile.

3. Make stakeholders aware of the cost of interrupting a project

I find the metaphor of a plane helpful: starting and completing a project is like flying a plane. If you bail out mid-way through the flight, the plane will not just sit there in the air waiting for you to come back to it, and you need some way to travel from the current project/flight to the next one. In fact if you're in the middle of a flight from Phoenix to Fargo and you're told that you need to interrupt that flight to take another plane from Denver to Detroit, you'll need to land the first plane in Denver (which is fortunately not far from your flight path—not always the case with real interruptions) and someone has to figure out what to do with the cargo and passengers. They won't just sit and wait forever.

The point of this for projects is that transitioning from one project to another incurs a large expense of time and leaves a lot of lose ends that have to be dealt with.

In a project there is obviously and inevitably a lot that goes on in your head while you work and not every thought can be serialized to a written medium, and not every iota of those thoughts that are serialized will remain when deserialized. Although we can partially capture our thoughts in writing, it is very much a lossy format.

The problem (as I see it) is that project managers and other business people think of projects as a series of steps that can often be reordered at will (unless there is an explicit dependency on their Gantt chart) and can be easily distributed amongst people or delayed until it is most convenient for the business.

Anyone who has done any amount of programming knows that software projects cannot be treated like Lego blocks to be moved around any way you like. I find the metaphor of air travel at least gives stakeholders something concrete that they can think about that clearly cannot be treated as a series of disparate steps to be reordered on a whim. It at least makes it easy to understand your point that there is a cost to such interruptions. Of course it is still their decision, but you want to make them aware of this before they interrupt one project to give you another. Don't be combative, but offer helpful information and the helpful perspective of the developer, ready to do whatever they need from you, but just offering information that they might not be aware of if you don't tell them.


In short:

  1. Write down everything you're about to do, even if you don't think you could ever possibly need it written down. Even a short pencil beats a long memory.
  2. Brainstorm the big picture on a physical whiteboard that you have persistent access to.
  3. You might avoid project interruptions if you make decision makers aware that there is a cost to such interruptions, and at least you will have set expectations so they know the project will take a bit longer when you resume it.
share|improve this answer
1  
Stakeholders assume they're paying a professional developer who is commenting & documenting code so he (at a later time) or someone else (at any time) can take over the project. Of course their assumption is wrong most of the time. –  JeffO Jul 24 at 14:14
    
And you should be commenting and documenting! I hope you didn't think I was suggesting otherwise. (And by the way I agree with your comment.) –  iconoclast Jul 24 at 14:18

You can look up the project's history in your version control software from three months ago. Read your commit messages and most recent diffs to get an idea of what you were working on.

share|improve this answer
    
I'm surprised this answer was not upvoted. Version control log is an excellent way to know where somebody was several months ago when the project was temporary suspended. Clear log messages help a lot. Diffs and lists of changed files are an additional way to get an image of what was going on with the project before suspension. Finally, there are more developers who use a version control compared to the number of developers who use a bug tracking system (or even a simple to-do list), which makes this answer valuable to more people compared to the highly upvoted answer by Scott Whitlock. –  MainMa Jul 22 at 20:51

Using a source-control system with proper branching and merging strategies, in conjuction with an issue-tracking systems (like Redmine, or GitHub) help you compartmentalize the changes you've made, give them direction, and document your missing 'context' as a natural part of the workflow.

  1. Before you start a code change, make sure there's an 'issue' logged in your issue-tracking system. That covers the missing "what was I doing" piece of your work.
  2. Create a branch in your source-control system, and make sure your changes in that branch are related ONLY to the afore-mentioned issue. This will help you isolate changes, and give you a history of the change, answering the question of "where did I leave off?" once you come back to work on it later.
  3. Once you're done with the change, merge it back into your trunk, and close the issue.
share|improve this answer

There's a lot of long answers. This is a short one about what helps me the most:

  • Clean code.
  • Clean code.
  • Clean code.
  • Version control (diffs and commit comments).
  • A Post-It note or a Todo-List or a Kanban-Board (see e.g. Trello and Evernote)

However, Diffs, Commit comments, Post-It notes, Todo-Lists or Kanban-Board can be misinterpreted over time for the lack of context. So here's the one thing that is most important:

CLEAN CODE.

share|improve this answer

In addition to the suggestions about project tracking, ToDo lists, Trello, etc something I read once that helps if you're practicing TDD is to always step away from your project with a new failing test to implement whenever you return to the project (tomorrow, next week, or next month)

Sit down, do 'Run Tests', and pick up where you left off.

share|improve this answer
1  
This has two drawbacks. First, if you use continuous integration, consciously committing a test which fails is out of question. Second, if you're in a team of more than one, other people may not appreciate if you commit a failed test. –  MainMa Jul 22 at 20:53
1  
@MainMa i didnt say commit. Just locally. –  Pete Jul 22 at 21:16
    
My suggestion to any developer is to commit when he won't work on a project even for a few days. Things happen. Your PC can be stolen, or you may not be able to boot it tomorrow because RAID controller failed. You may leave the project and the other developer may take your place. You may be hit by a bus. You may erase the project locally because it takes too much place or because the virus killed your OS. So no, relying on an uncommitted code is not an option. –  MainMa Jul 22 at 21:24
1  
@MainMa then commit and push to a branch named next-steps. I'm not sure what your concerns about the specifics of revision control approach have to do with the basic premise of a failing test as an aid in kickstarting your brain when coming back to something. Again, this was proposed in addition to the standard approaches such as backlogs, to-do lists, etc. –  Pete Jul 22 at 22:54
2  
@MainMa: version control may have a lot in common with backups, but that's not its primary purpose. If you need a backup system, and the way you're using version control prevents it from fulfilling that purpose, then get a Time Capsule or something similar. You should never be forced to commit prematurely just to force your VCS to serve as a backup. And you should never be prevented from doing something otherwise beneficial because you're following a "commit everything immediately" policy. –  iconoclast Jul 23 at 13:56

In addition to the comments / todo lists / commits, it is important to be realistic.

Depending on the size, complexity and the state you left your work at, getting started again on a project could take a while. For a substantial codebase of many interacting components, it could take days to get up to full speed.

Good old patience will be useful.

When overwhelmed after coming back to a project after a while, I generally pick up the simplest and smallest unit of task and implement it. It keeps me from getting lost trying to remember a lot of things at once and bumps up the confidence a little bit. More often than not, I find myself automatically picking up increasingly bigger tasks in a few hours.

share|improve this answer

How can I document a project such that anytime I look back it shouldn't take me more than a few minutes to get going from wherever I left.

First off, this implies there is some high-level description and code structure in the project that you can easily grasp in a few minutes -- as opposed to a zillion lines of code with no apparent structure and no comments.

Are there best practices?

The following are best practices I adopted throughout a 20+ years career in very small to very large projects and they have served me and my teams well. Apply in the order listed as your project grows:

  1. Modularize your code (depending on the language and programming environment, use classes, modules, packages, components).

  2. Document your code. This includes summary documentation at the top of each file (what does this do? why? how to use it?), and specific comments at the level of functions, procedures, classes and methods (what does it do? arguments and return values/types? side-effects?).

  3. Add TODO and FIXME comments while you are coding. This helps to remember the whys and whats of quirks that will inevitably enter your code base and that later on will have you asking WTF?!. E.g.:

    //TODO shall actually compute X and return it
    ... some code that does not compute X yet (maybe returns a fixed value instead)
    
    //FIXME make this constant time instead of n^2 as it is now 
    ... some code that works but is not efficient yet
    
  4. Make a habit of drawing diagrams to document structure and complex behavior such as sequences of calls between modules/objects/systems etc. Personally I prefer UMLet as it is quick to use, creates nice graphics, and most importantly doesn't get in your way. But of course you should use any drawing tool that you find does the job. Remember that the purpose of any such drawings is to communicate succinctly, not to specify a system in minute detail (!!).

  5. Add unit tests early on. Unit tests are not only great for regression testing, but are also a form of usage documentation for your modules.

  6. Add code-external documentation early on. Start off with a README that describes the required dependencies to run and develop the project, how to install it, how to run it.

  7. Make a habit of automating repetitive tasks. E.g. compile/build/test cycles should be scripted by some form (e.g. in JavaScript use grunt, in Python fabric, in Java Maven). This will help you get up to speed quickly when you come back.

  8. As your project grows, add more documentation by generating source-code docs (using some form of JavaDoc-style comments and an appropriate tool to generate HTML or PDF from it).

  9. If your project grows beyond a single component and has some more complex deployment to it, be sure to add design and architecture documentation. Again note that the purpose of this is to communicate structure and dependencies rather than minute details.

share|improve this answer

For me, I find the simplest method of resuming projects is just to keep a constant record of notes on your work. I find that Microsoft's 'OneNote' is particularly good for keeping and grouping pages of notes. In particular, the search bar makes it extremely easy to quickly find your notes on something.

Here are some things I do within OneNote which help me to resume progress on projects:

  • Daily/Weekly Logs - Keep a daily or weekly log of progress to help you figure out the progress that you've already made with a project.

  • To-do list - I have a general to-do list, but I also keep a separate to-do list for the projects I'm working on so that I remember what things I have yet to do for a project. I sometimes also leave //TODO: items in my code.

  • Project Notes - Things I note include links to issue/project tracking items, snippets of code, issues encountered, decisions made, plans and descriptions of potential solutions, list of code changes, links to code repository directory, emails for the project and links to project documentation.

So, whenever I go back to a project I can open up my notes and almost instantly I can see how much progress was made on the project, how much work is left to do and even see my train of thought.

share|improve this answer

I keep a daily journal of the work I do. What did I do today, what was difficult today, what is the next step, what ideas did I have today for the future. I also add a bit of narrative about what the day was like: was there an interesting conversation or meeting? Did something anger or delight? This helps to put things into perspective when I later read my journal.

When I come back to a project after a while, I read the last few entries in the journal to get up to speed with the project. All those little day to day details are incredibly important for remembering the development process. They really make lot of difference compared to a todo list or regular project documentation, since they remind you of what it was like to work on the project, and not just how to use the product.

share|improve this answer
    
this doesn't seem to offer anything substantial over points made and explained in prior 11 answers –  gnat Nov 16 at 8:23

For simple projects, I do this:

  1. A simple README file in the root directory (which, therefore, will also end up in version control) where I note whatever pops up while developing: things to do, bugs, improvements/ideas. That is the first file I will read should I have to put the project on the back burner.
  2. TODO/FIXME/XXX comments
  3. I often also use ToDoList
share|improve this answer

protected by ChrisF Jul 26 at 11:04

Thank you for your interest in this question. Because it has attracted low-quality answers, posting an answer now requires 10 reputation on this site.

Would you like to answer one of these unanswered questions instead?

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