Write good commit messages

Dear new developer,

Take the time to write good commit messages. Such messages communicate intent across time, and live very close to the code. Here’s an example of a bad commit message:

Updated the code.

There’s no intent here. Yes, of course, you did update the code. Why? Inquiring minds want to know.

updated the acceptForm method to accept a URL escaped code

This is slightly better, but is still no good. This is a bad commit message because it focuses on the how but not the why. Why did the acceptForm method need to be modified?

In general, great commit messages focus on the intent of the change, not the mechanics. Why was this change needed? What drove it? What would you want to know about this reasoning or decision a year from now? What would you want a new team member approaching this code base to know? These are good questions to guide you as you consider your commit message.

Document the reason for the change because those reasons can get lost. They may be captured in a doc, yes, but git log is far more accessible than a doc. In some teams and situations, you won’t even have a document to capture the purpose of the change; it might have been just a hallway discussion, a ticket filed by a customer, or a change made by a single developer without consultation. Code reviews and pull requests can help capture intent as well, but again, they may or may not be easy to find; they certainly won’t be as easy as git blame.

Here’s a good commit message:

Updated the acceptForm method to except a URL escaped code.

Client ABC was sending a URL escaped code instead of what we expected. This means that the system was throwing a null pointer exception. Investigated changing client ABC, but that would involve releasing another version of the client library, which we are deprecating.

More details in this thread: http://slack.com/aaa/bbb


Feel free to write as much as you need to communicate intent. It’s also good to have a summation in the first line, then two newlines and then as much explanatory text as you want. I like to do this on the command line so that it’s easy to edit.

If the mechanics are particularly tricky or misleading, that’s one time you may want to focus on the how. For example, if a piece of code is purposefully using a particular deprecated data structure for compatability reasons, outline that in the commit message.

An additional benefit is that this forces you to think about what you were trying to accomplish with this change. If you make more than one change at a time, you can use git add -p to commit only a section of a file.

If you make a mistake and you are using git and haven’t pushed to a remote, you can use the --amend command to make a change to the most recent commit message. You can also use the git rebase command to rework your entire commit structure, including getting rid of “there was a typo” commit messages. Here’s a video about a rebase workflow:

Presentation on git rebase

Now, I’m definitely not perfect about this. I sometimes make errors in my messages. In that case, just as when I make any other mistake, I find out what I did wrong and try to do better next time. You can also use tooling to avoid errors. I have heard of people use tools like Gitcop to enforce rules, but haven’t used it myself.

You can also add a git hook, as a team require all feature branches to reference an issue number, and parse the branch to put the issue number on every commit. Or you can modify that git hook to append the branch name, as outlined here. I’ve done this on different teams and it’s low effort and effective. This isn’t perfect because you can still have a commit with a one word message, but at the least you have some link between a code change and the impetus for it.

Whatever you do, find out what the team norms are around this. Have your commits meet at least that level of detail. This norm may be delivered when you start, or via code reviews, but you can ask as well: “what are some great commit messages that I should model mine after?”

Remember, the purpose of a commit message is to communicate intent. Strive to do that and you’ll thank yourself later when you’re trying to figure out what is going on.



A Crash Course for Your First Job in Software

Dear new developer,

This post, “They Didn’t Teach Us This” is a great read.

There’s a curious phenomenon that happens when new web developers take their first job. You’ve just gotten your CS degree or graduated from bootcamp, and you’ve spent months or years learning to write efficient code, practicing for interviews, and building portfolio projects. Finally you’ve accepted an offer, and you’re thrilled⁠—you’re now a Software Engineer™. You march in on your first day, your head held high. And then, in your first week of work, it dawns on you just how little you actually know.

To be honest, that is what this whole blog is about.

But never fear, the author has some suggestions. There are a whole number of items that matter for professional code (like accessibility, scale, and reliability) that don’t really factor into personal projects. He outlines these and a few other concerns. The author also talks about process (with git, environments and deployments, among other things):

So, what exactly happens during a deploy? To start, you’ve been working in a local “development” environment, which gives you the ability to see changes nearly instantly. However, what gets deployed to production often aren’t the exact files you work with on your local machine.

I didn’t have much process when I was starting out as a new developer, but the older I get, the more process matters to me, even when I am the only developer. It takes the complex and layers an abstraction over it, making it easier. In a very real way, the actual content of a process matters less than that all parties agree to it.

The whole article is worth a read.



Write that down!

This is a guest blog post from John Obelenus. Enjoy.

Dear new developer,

Even when I was a kid in school I hardly wrote things down. That’s why we had textbooks after all! I was baffled by other students in college furiously transcribing every word that came out of the professor’s mouth. Now I have a career in the world of software where we track everything. Git holds all the code commits, email is never really deleted, and project management and issue tracking tools keep track of what we’re doing and have done. How could anything go missing?

I constantly looking for things and cannot find them. I get a bug report, look at the code and say to myself “That is obviously wrong, let’s fix it.” I look at the offending commit that introduced the bug (of course it was me). But what is not there? The reason for the change. So I look at the project management tool we use. And someone definitely asked for a change, but, I’m still not sure why. So I search through my email for the few days before I made the change, and…nothing. I still cannot really figure out why we all decided to make a change which introduced a bug.

Or, worse yet, someone asks for a change. All well and good. Then a month later, someone asks to change it back. So you shake your head and make the change. Then someone is confused why this is happening, and calls a meeting and invites you to help figure it out. What are you going to bring to this meeting? Did you write anything down? I never used to. Now I do.

Now I have a notepad next to my laptop. And I have a notebook on the shelf. I make better use of git messages and write down who asked for changes. When working on a feature, or a bug, and find something…“interesting” I make a Github wiki entry explaining it. I write a comment in the code base explaining it. There are two kinds of documentation — useful documentation, and redundant documentation.

No doubt many people have told you to comment your code. I hope many people have told you never to comment a loop with // loop over the array. That is not increasing clarity, its just duplicating what the code is doing. Adding noise, not signal. My contention is that comments are rarely useful for explaining “What this code does…” but rather, explains “Because of X, we are going to do…”.

Future you is going to be very happy if you start documenting the intent behind what you’re doing. Good code is easy to read. Bad code is capable of being understood with time. But code doesn’t tell you why you’re doing all this work in the first place. Maybe something has changed and you don’t even need this code anymore — deleting code is the most satisfying feeling. But you won’t know unless you know the intent, the purpose, of the code. And the rest of the folks you’re working with are going to be very happy as well.

If you write everything down (and make it public), they won’t need to tap you on the shoulder when you’re in “The Zone” to ask. When someone wants to set a meeting to understand why things are “The Way They Are” you already captured that information. You can send them the link and kill the meeting (Ok, maybe killing meetings is more satisfying than killing code).

We only have so much time in our life, and we already work long hours. Let’s make future us happier by writing things down, so we don’t have to figure it all out again. We figured it out once when we wrote the code. So capture the knowledge in that moment in time. And Write It Down!


John Obelenus

(Previously published at Medium)

John Obelenus solves problems and saves time through software and crushing entropy



Be a Just in Time Learner, part I

Dear new developer,

There’s the concept of a JIT compiler. I was first introduced to it with the HotSpot Java compiler. The idea is that a compiler can look at code and find the code that executes often and optimize it, sometimes compiling it down to faster code, sometimes unrolling loops. I’m no compiler expert or even intermediate, but the results speak for themselves. JIT has spread elsewhere (python, ruby, javascript).

As a new developer, you should be a just in time learner. Just like the compiler watches to see what is used often and then optimizes the code that runs fast and often, you should do the same. That’s why I recommended you learn version control and a text editor. These are tools that, as a software developer, you spend a lot of time in. So learning them well will save you time in the long run.

But what about the intricacies of a language or framework. That’s important too. But it depends on how often you predict the issue will come up.

Here’s a great chart from XKCD.

If you spend two hours remembering how to do something but you only do it yearly, and you learn it well enough to do it in one hour, you save five hours over five years. Does this make a lot of sense?

So, basically, I’m saying optimize for the things you do often. Another way you can do that is to make what you learn do double duty:

  • When you learn SQL you learn a way to query across multiple different databases.
  • When you learn javascript, you are learning a language that you can use on the front end (in the browser) and the back end (on the server).
  • When you learn vi keystrokes, you can use them to edit a text file in a terminal on any unix machine, on the command line to navigate your history and directory structures, and in eclipse or visual studio.



Making mistakes is OK

Dear new developer,

One time, not too many years ago, I was using git. I had used it for some personal projects, but hadn’t used it in the team setting before. We were using this git branching model. I was creating feature branches and working on them.

However, often I would be working on the same feature branch as a colleague. The first couple of times I was doing that, I used ‘git checkout -b <branchname>’ to checkout the branch. I’d then pull down the remote branch ‘git pull origin <branchname>’ and work on it.

Do not do this. Doing this will checkout a branch named <branchname> but it will be off whatever branch you were previously on. The pull will then merge the remote code. So you’ll get the code you want to work on, but there will be other code lurking. No good!

Instead, run ‘git fetch origin<branchname>’ and then ‘git checkout <branchname>’.

I point this out not because I’m trying to teach you version control (though you should learn it).

I point it out because this was a mistake. I don’t think any code escaped into production, but it definitely confused some team members and could have been very bad. It’s one of many many mistakes I’ve made in my career.

Mistakes happen to everyone. It’s important to learn how to handle them.

First, find out what the mistake was. You need to have an understanding of the mistake so you can avoid repeating it. This may be a conversation with another team member, research, or both.

Second, acknowledge that you made the mistake. If you work in an environment where you cannot acknowledge errors, make plans to leave as soon as possible. You don’t have to wail and beat yourself up, but just saying “oh, wow, I really screwed up that git branch stuff. Sorry!” is going to let people know that you made a mistake and that you are adult enough to know it.

Third, clean up your mistake. You may need some help doing so, but part of taking responsibility for your mistakes is fixing them as best as you can.

Fourth, avoid making the same mistake again. This may involve keeping a notebook, a writing a blog post, or just committing the correct solution to memory (this depends on the scale of the mistake). Bonus points if you do this in such a way that other folks, either internal (wiki page, slack message) or external (blog post, stack overflow question and answer) can benefit from your mistake.

Mistakes happen. It’s OK. Don’t pretend you don’t make mistakes, own up to them, and try to make new ones rather than repeating.



Learn Version Control

Dear new developer,

If in doubt, put it under version control.

Version control is a way for you to keep track of the core nuts and bolts of code, which are files on the filesystem. Version control lets you make mistakes, err experiments, and roll back time to when things worked. Version control lets you see who made what changes when to which files, so that when you need to find out who to ask about the bizarre function in class XYZ, you can.

Don’t be surprised if that person is you.

There are many systems of version control. What you use depends on your needs, the most important of which is how many people are interacting with your system. But something, even a crufty old system, is far better than nothing.

There are plenty of free version control systems out there, so if you aren’t using something, set up one of the free ones (or better yet, use a hosted service) and give it a try. Github, bitbucket, gitlab, all are happy to walk you through how to store your code in their system. Learning one of the modern version control systems will help you integrate into any team, because running a software project of any size without version control is a foolhardy endeavor that only is typically tried once.

There are some items that don’t belong in version control. Large binary files belong on a storage system like S3. Secret information, like a password, is better kept out of version control and in a secrets manager or environment variables. Documents that are going to be edited by nontechnical users should probably use a shared document repository (which will likely have versioning built in, but hidden).

But everything else, all the source code and build scripts, all the infrastructure setup and documentation, all the assets and sql scripts, those should be kept in version control.