I work on a fairly complex service layer, and whenever I return after a long weekend—or even just a couple of days away—the first 30–60 minutes often disappear into rereading my own code and reconstructing what I was thinking.
Better comments and documentation help, but I'm looking for practical habits beyond that. Do you leave yourself a note at the end of each session describing exactly where you stopped and what to do next? Do you intentionally stop with a partially finished task, a failing test, or something else that makes the next step obvious? What methods have actually reduced the context-switching cost for you?
4 Answers
For the broader codebase, I rely on a lightweight project overview: architecture notes, task lists, diagrams for important flows, and documented conventions. That reduces the amount of context I have to rebuild, especially when other people have made changes. One warning: documentation has to be updated with the code. A stale comment can be worse than no comment, so if a function changes, update or remove any comment that no longer describes what it actually does.
I keep a project task list with an “In progress” section, and it contains one current item written for my future self. I describe what I was doing, what I discovered, and the very next action. For a tricky problem that note might be several paragraphs; for a routine task it could be as short as “finish the accessibility check on the new item form.” The key is to write what is true right now rather than a vague reminder like “continue debugging.”
I do the same, and I try to capture the current reasoning and stopping point—not just the task name. That makes the note useful when the problem is more complicated than a simple checklist item.
The most reliable version for me is attaching the note to the code itself. I commit work in progress on a branch with a message explaining what’s complete, what’s broken, and the next step. Then I can come back to the commit, diff, and history instead of maintaining a separate note that might drift away from the implementation.
I sometimes stop with a test failing or a function intentionally incomplete, as long as the interface and overall direction are clear. The failure gives me an immediate entry point when I return. I also make small commits that represent understandable chunks of progress, so the branch history tells the story if I lose the thread. For longer breaks, I’ll add a larger note covering what is done, what is missing, and what I was about to try next.
That distinction makes sense to me. I’m mainly struggling with the immediate work in progress, but having a current overview would probably make the general re-entry process much less painful too.