Software Engineering Stack Exchange is a question and answer site for professionals, academics, and students working within the systems development life cycle. It only takes a minute to sign up.
Sign up to join this community
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?
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 < 0but 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
xcould 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.
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.
todo target in your makefile that dumps them out is also useful.
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.
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:
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.
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.
In my opinion, there are two parts to "resuming" a code project:
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.
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.
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.
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:
(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.
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.
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.
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.
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.
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:
Use version control this gives you a free track record of what happened, when and who applied the changes. It also gives you easy fall back to an earlier version at any time.
Modularize your code (depending on the language and programming environment, use classes, modules, packages, components).
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?).
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
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 (!!).
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.
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.
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.
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).
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.
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.
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.
There's a lot of long answers. This is a short one about what helps me the most:
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:
main, which for a significantly sized program will be rather abstract. I can then dive deeper, and see the architecture of how the program cleans up itself, for example. Further, clean code means that functions/variables/etc. have names that make sense and make a statement about their meaning. If I, instead, write Spaghetti/Write-Only-code, I will often wake up the next morning/month/year, look at my code, and the only thought will be wtf-did-i-do-there. It's the same when..
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.
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.
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.
For simple projects, I do this:
