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

[#123]

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.

Sincerely,

Dan

How I Got a Job Two Weeks After My Coding Bootcamp

This is a guest post from Randall Kenna. Enjoy.

Dear new developer,

Two weeks after I graduated my coding bootcamp, I had an offer. Two weeks after that, I started my first engineering job at a small startup.

Here are some of the strategies I used.

Treat your job search like it’s your job.

I was exhausted after I graduated from my bootcamp. But I had spent more than$15,000 on tuition and living in San Francisco so I knew I needed to get a job quickly to prove the financial investment was worth it. It was so tempting to just spend those two weeks napping on my couch and recovering from the most grueling process of my life but using the momentum I had from graduating the bootcamp was critical. I had read about a lot of students that had let their skills get rusty and it had taken 6–12 months for them to find a job.

From the hours of 9AM to 6PM, I was job hunting. I was obsessively updating my resume, finding new jobs, reaching out to connections, finding meetups to attend, and honing my skills. After 6PM, I wouldn’t respond to recruiter emails or do any prep work for interviews. I used that time to recuperate and prepare for the next day.

Optimizing my LinkedIn

The company that I ultimately ended up taking an offer at actually found me through my LinkedIn. For all the applications that I sent and meetups that I attended, they ended up finding me and asking me to come in for an interview.

I filled out my LinkedIn with my prior jobs to show that even though I didn’t have a ton of engineering experience, I had a past career where I had been paid to code a little in some of my past jobs. I added every course I had taken and every certification that I had gotten during the bootcamp to show that I was very interested in engineering and it wasn’t just a job to me.

Quickly moving on from companies that weren’t a fit

A few companies had interview processes that were equivalent to Google. They wanted a coding bootcamp graduate to be able to solve complex algorithms that even a software engineer with a CS degree and years of experience would have struggled to complete.

I would have spent so much time preparing for just one interview at one company when instead I could use that time to go through the interview process at several companies. I told the company that the process was far too intense for a junior engineer and moved on.

You don’t have to use this strategy however if you’re willing to put in a lot of time learning algorithms and focusing on building some CS foundations. Some people in my cohort focused on their algorithm skills and it took a little longer to find a job, but they started out with a better title and higher pay.

Build a coding portfolio

Thankfully, my coding bootcamp had helped me create a large portfolio with several applications. I was able to take this to prospective companies and discuss what I had learned during the project. In my final project, I had focused mostly on frontend so I took that work to companies and detailed exactly what I had worked on.

If you don’t have a portfolio yet, just get started on something small and push it up to GitHub. Each time you create a new project, challenge yourself to make it a little more complex than the last project.

Proving I was eager (and desperate) to learn

Two companies told me I could build a project in the framework that I was most comfortable in. But I knew that if I spent a little time learning the framework that they used, I would improve my odds of standing out.

Over the weekend, I taught myself the framework one company used and built a small (and very barely working) app that used it. I was able to discuss the principles of the framework and even though my app broke during the demo, I got the job.

This was a risky strategy because I ended up not spending any time learning the other framework for the other company but it worked out in the end when I received an offer from the company.

Focusing on my strengths and not my weaknesses

I knew that I wasn’t going to do super well at companies that focused on algorithms and prioritized having a CS background, so I intentionally found companies that wanted to focus on mentorship and had real world interviews.

In the interviews, I discussed how I had prior career experience that would benefit them if they hired me and I had been coding at those jobs as much as I could.

It definitely wasn’t easy but anyone can get a job in coding if you treat your job search as if it’s your job and keep improving your skills.

Sincerely,

Randall

This post was originally published at RandallKanna.com.

Randall Kanna is a Senior Software Engineer at BaseHQ, speaker and O’Reilly author. She’s formerly worked at companies such as Eventbrite, and Pandora.

Coding is like a puzzle

Dear new developer,

I have recently been doing a lot more puzzles. It’s a low tech way to spend time with the family. As I was working on one recently, I snapped two large sections of a puzzle together. It was very satisfying. I mused on how working on a jigsaw puzzle is a lot like coding. You work on small pieces, checking back in periodically with the big picture. Slowly, slowly, you build up toward your goal, which is a working system or a finished puzzle.

Puzzles are like software development in other ways too. For one, it helps to take time away from both a puzzle and a software system periodically. Often when I take a break, I return with both renewed excitement and additional insight. The break can be a night’s sleep, a pause for lunch, even something as simple as a short walk.

Another way I can make progress in either case is to shift my focus. When I’m working on any problem, there are multiple tasks that need to be done. Some are hard, some are easy. Some require deep work, some require conversations with other team members, domain experts, or customers. Just like you can shift from from one section of a puzzle that has you stumped to another, shifting from one software task that you need to do to another is a good way to maintain forward progress. Nothing saps my motivation more than beating my head against a wall.

Finally, the satisfaction when you bring all the pieces of a software system together is similar to when I finish a puzzle. Watching someone use a completed system which I had a hand in building is a joy.

However, puzzles aren’t a precise analog to software systems. There are some substantial differences.

First off, most software systems are far larger than puzzles, often involving the efforts of tens or hundreds of people. Puzzles seem to max out at around four people or so, and even then there are delays where one person is waiting for the box or to get access to an area of the puzzle. And software systems are built to work on problems that affect people’s lives, as opposed to being an amusing hobby.

Also, with a puzzle there is a known end state; the picture on the box is what you’re aiming for, and you can constantly checkpoint against that; unless of course, you’re working on one of these. An essential difficulty of software is that the end state isn’t typically known with anything like that level of precision. In fact, in most systems I’ve built, the end state changes as the team builds and learns more about capabilities. Check that, I remember one time we had a prototype mobile app in Cordova and we were able to rebuild it using native libraries. Of course, that got outsourced, so maybe it’s better that the end state changes.

Another difference is that with puzzles I always start with the easy stuff. The corners and edges of a puzzle are usually the first major components that are done. With software, that’s a recipe for disaster. I always work on the hard parts as soon as possible, preferably first, because doing so decreases the risk of a failure. There are always more and less risky sections of any project and my advice is to tackle the areas of least certainty and highest risk as soon as possible. It’s scary, but if you wait, it’ll only get scarier.

Sincerely,

Dan

Show up

This is a guest post from Elise Shaffer. Enjoy.

Dear New Developers,

As I sit down to write this letter, I’m struck by the thought that I don’t know you. You could be like me, a person who’s loved computers since she was nine years old and has taken every opportunity to learn more about them. You could also be one of the many people who’ve recently graduated a coding bootcamp after spending years in another career. You might have an experience somewhere in between or vastly outside the two.

So, the challenge put to me is to give advice about starting out in development that would be applicable to you given the wide range experiences that might have brought you here. Thinking about that led me to a revelation that the best advice I could give is to show up.

Software is about human relationships. I know this is a point that’s appeared on this blog before. I won’t rehash all the reasons that’s true, but I will use it as a starting point to say that it’s important to have people with diverse experience designing software. It’s important that no matter where you are coming from that you show up. Bring your experiences, struggles, values, and tastes to your work as a developer.

You’re starting out and will probably feel that you need to catch up to your peers. Certainly, there is always more to learn in software development. But you also have so much to teach those around you. Maybe you have an aunt who needs assistive technologies to use the web. Maybe a computing error caused trouble in your previous career. It’s easy to get lost in everything you don’t know. But, it’s just as important to draw on your previous experiences. For example, maybe you used to work in manufacturing safety systems. Safety is incredibly important in manufacturing and it’s also important in software. Or, you might have taken foreign language and culture electives in college that help you understand how design decisions will be received internationally. How can those experiences help you work on projects with your team?

Don’t be afraid to ask stupid questions. It might seem like a stupid question to you, but it’s more likely that what you’re asking is something the rest of your team takes for granted.

Software should support people. In order to do that it has to understand people and the only way to ensure that, is for those designing it to draw upon the biggest well of experiences possible.

There is always more to learn about programming. But, you already know so much that you don’t even realize. Bring that knowledge and experience to your work as a developer.

Best,

Elise

Elise has been fascinated with computers since she was a child. She’s worked in the field for ten years across a few industries and now works as a Senior Software Engineer. She also blogs at eliseshaffer.com.