menu

The Programmer’s Follow-Through - Commits & Code Reviews

In sports like golf, baseball, basketball, and others, it’s important that you follow-through with movement after the ball has been released. A proper follow-through is a reflection of what happened before release/contact. Programming isn’t that different. When you write code, it’s important that the last keystroke you make in your editor is not the end of your process. The follow-through could be translated to your commit process and code reviews. The commits should reflect the work that was done and the code review helps ensure the code enters into production gracefully.

Code Commits

When writing code, it’s important to break up your work into small deliverable chunks. It helps to minimize complexity and deploy faster. Each task or feature you’re asked to work on can generally be broken down into even smaller chunks. Each of those can be committed separately with Git (or your preferred version control system).

Small Commits & Clear Commit Messages

Before digging into your code, consider what your commit message is going to be. Keep it simple. Ensure it defines the value it provides to the codebase. If it is related to a bug, it may be helpful to add some detail related to the bug. If it helps, write it out before hand and follow up using that commit message when your code does what your commit message states. Below are some characteristics of good commit messages:

  • The first line is 50 characters or less
  • It defines the reason why the commit is necessary
  • If you are using an issue tracker, it is helpful to include a link to the issue/card on line 3
  • A brief summary on line 5 to provide extra clarification as to the need of the commit and any side effects the commit may have on the application.

So, rather than writing `fix contact form`, write something like:

—-

Clarify contact form with flash message and redirect to home page

https://trello.com/card/url

The previous message in the contact form did not provide a clear
submission message. It now redirects to the home page with a
flash message confirming the message has been sent.

—-

Slices, Foul Balls, & Air Balls

An unclear commit message can be a sign that work was not appropriately broken down into smaller chunks. It’s likely that it has become more complex and took longer to complete because of it. For example, a change to the contact form should not include a change to the authentication form. Keep changes simple and deliver earlier. Another advantage to this is it keeps potential problems after deployment isolated.

Git blame can be a useful tool when you run into a problem and want to know why a line of code was written. However, when you find the change and the commit was made in a huge commit with a message of “New feature” it doesn’t provide much context to help. Think about this even when you are making a minor change and try to keep the message clear.

A Graceful Finish

Pull requests and code reviews complete your workflow gracefully by ensuring that the code that is merged in meets your team’s standards. At this stage, the reviewer should navigate through your changes commit by commit adding comments where there are any style guide violations or ideal opportunities for refactoring. This is one example of where it is important to have clear commit messages. This enables the reviewer to know the context of changes you have made and go into the review with that expectation.

Any changes that come out of the code review should have additional commits created and pushed back up for review. Again, keep commit messages clear for the reviewer.

The Retrospective

As a part of your normal sprint, consider making an effort to simplify your commits, clarify your commit message for review, and engage in a code review to ensure quality code is getting merged into your production builds.