As engineers, we enjoy solving technical problems and enjoy the results of our hard work. But sometimes, our development suddenly and mysteriously stops working, and we get stuck trying to figure out what happened. Then, hours later, we realize it was a really dumb mistake or oversight. Those times are really unfulfilling and frustrating.
To help you avoid this frustration, here’s list of lessons that have been painfully burnt into my heart over the years.
1. Save the file.
Yeah, we still forget to do this sometimes. We were supposed to have permanently learned this lesson during our first ever Hello, World program, but sometimes we still forget. Many IDEs have an autosave feature, but watch out when using that same IDE on another machine, since the feature might not be switched on. I’m more likely to neglect saving when I switch between buffers or tabs a lot.
2. Restart stuff.
We know that we have to restart the server/service(s) when we modify certain components, but sometimes we forget that a server’s even running at all. And this is especially difficult to remember after we’ve made several changes that don’t require a restart, followed by one that does.
With complicated development environments, it can be helpful to start small in your “restart scope” and then get bigger. Start by restarting only the service that’s directly affected by your changes, then move on to restarting all services. After that, consider restarting your IDE, restarting your entire system (e.g. if system packages have just been updated), or running make clean or equivalent.
3. Edit the right file.
I was once baffled when I removed a certain line of code and noticed the behavior of my web application didn’t change at all. After looking at it for a few minutes, I became excited and started to believe that I had found a large chunk of unused code that I could delete without affecting anything else. But I was mistaken: I was editing a copy of the source file, not the real thing.
Our projects often contain directories like “target” or “cache” that contain these sorts of copies that are usually created when your project is rebuilt. It can be easy to inadvertently open one of these files by mistake, especially when using a fuzzy file finder, which suggests files to open after you type in a few letters of the filename. Set some time aside to identify the directories that don’t contain source code in your project, and consider configuring your file-finding tools to ignore them.
4. Migrate the database.
Trying to run with an old database schema is another puzzling problem to identify. This happens when we pull schema changes into our code branch but then neglect to migrate our database.
We tend to do this when we’re getting ready to push some code that we’ve finished: we merge or rebase with master, but tests and features suddenly break. When this happens, it may seem like we’ve resolved conflicts incorrectly, or maybe that the master branch is broken. But investigating the errors closely will point to the root issue: the database needs to be migrated.
5. Work out of the right branch.
I was once interrupted right after I had finished implementing some front-end changes, but before I had started on the back-end. A teammate had asked for some feedback on some code that he was working on, so I checked out his feature branch and took a look. After looking it over with him, I implemented the rest of my feature. It didn’t work at all, and more confusingly, I couldn’t find the new front-end classes that I had written earlier.
Eventually, I figured out that I had forgotten to switch back to my feature branch after I was done helping my teammate. To get out of that mess of commits, git rebase was a big help. I also use an oh-my-zsh theme to constantly display my currently checked out git branch on the command line.
I do my best to steer clear of these issues, but there’s always a chance of getting tripped up on one of these or something else equally dumb. If you get completely stuck and can’t figure it out after a few minutes, ask for help. Here in the Detroit office, it’s common to hear one of us say, “Hey, could you take a look at this and make sure I’m not going crazy?” If no one’s around at the moment, take a break to let your mind see the bigger picture, or sleep on it and come back the next day.