Tag Archives: Code Review

How To Write a Valuable Commit Message

Fixed.

Fixed.

Fixed.

The best commit message out there. The one that tells you absolutely nothing about anything.



Commit messages are a funny thing. They’re not very valuable when you submit them, yet when a bug pops up in production or you’re building a release, knowing the right place to look (especially if it’s not your code change) can save hours.

The commit message is one of those things you do so that you can reap the benefits when needed. Sort of like locking your door at night before you go to bed. You don’t expect to need those locks, but when you do, you’re grateful you had them in place and locked.

So what can make a great commit message? First I think it’s better to try and ask, what makes a great commit? This question can actually be trickier to answer but I think answering it, helps us write a better commit message.

Advertisements

A good commit, can best be seen as a lot of commits. The reason being is that when you commit often you can end up with a best of both world scenario.

You see some would prefer one giant chunk of completed code to complete a feature. This let’s you see the entire solution together as one. It can be difficult to review or push changes to a main branch, one-by-one. The good news is, most source control solutions now offer a way to squash (combine) all of the new commits on a branch before merging them into main, making it incredibly easy to accomplish this.

photo cred: Melanie Hughes

However, seeing individual commits can let you break things down more easily. You can get an idea of how the changes developed over time and it can help you pinpoint issues. You can also write more frequent commit messages instead of one really long message on a single massive commit. Oh and if you ever need to switch gears and work on that production bug ASAP, having your in progress work already committed makes it easy to switch to your main branch without losing any work.

Now that we know we want to have lots of little commits, let’s talk about what to put in the commit message. There are a couple of key details to include in your commit message based on your branching strategy. If you have a good branching strategy your commit message can contain more or less information as needed but you typically want to try and cover the following:

Include the ID of the related work ticket.

Include the type of commit.

Include a brief description of the change.

Advertisements

These three items make up a tasty commit stew and can be viewed as: ID-Type: Message. Let’s look at couple of examples.

23489-Feature: Added new items to the drop down on search page

23489-Bug: Fixed the drop down from not opening completely

89012-Refactor: Cleaned up old, duplicate code for invoicing

1203-Dependencies: Updated dependencies ahead of new features

Each of these commit messages provides enough detail for you to be able to tie back the code changes directly to the work item they belong to as well as what the change is so you can easily help identify potential issues.

When pushing these changes to a main branch you then have two options, you can either hang on to the individual commits (which can be useful for future debugging) or you can squash them all together and push the changes as a whole feature to the main branch (which will give you a cleaner history for the code base).

At the end of the day, there’s no right way to write a commit message. There are however, wrong ways… The key is to do yourself and your fellow developers a favor and make it as easy as possible to identify what the code changes are.


How I Conduct a Code Review

Code reviews have been and always will be tricky business. If you’re familiar with performing code reviews or having someone else review your code, you hopefully can understand and see the benefits. For some though, a code review can be a hit to the ego. Here’s how I’ve approached code reviews and what I find works best.

First and foremost, you have to have some formal code review practices in place. If you don’t, I suggest you start by offering up your services. Not in a way that says, “I’m a better developer and I know more so let me make sure your code is right.” If you give off any type of vibe like this, your code review is going to come off as arrogant and unwanted.

Offer your services for a code review as a means to help take some of the pressure off of the other developer. Your code review is to help them look for bugs, typos, or little details they may have missed. It’s also to provide a challenge back to that person to ask both you and them to think critically.

Once you’re able to agree to a code review with your peer, the next step is actually conducting the review. But how do you go about performing a code review? What should you be looking for? What really works? I follow these same steps, every single time, and find they always hit the nail on the head.

Advertisements

Step 1: Compare

Before I actually do any real review, I start by performing a compare. There are a lot of ways to compare the changes, before and after, and I’ll let you figure that part out. I start with a compare to get a sense of what I’m going to be reviewing.

How much code has changed and how much did it change by? At times I may find that too much has changed, making the review nearly impossible. When this happens, it’s best to recommend that the developer try to create smaller commits. BOOM! You just gave your first piece of code review feedback.

When looking through the compare, don’t try to focus on individual lines of code yet. We’re not at that stage. Stay at a high level and focus on structure and getting familiar with what you’re working with. Are there new classes or functions? Is it a complete rework or just a quick change? Are there unit tests? Did the developer leave any notes for the reviewer? Focus on gathering information and making an initial assessment.

If I suspect that the developer is not done working on an area or that there may be major, additional changes I will stop my review right there on that area. There is no sense in going to the next level of review if the section of code will potentially be refactored or changed. Save yourself some time and simply give the developer your high level assessment and tell them you look forward to diving deeper once they are closer to completing their changes.

photo cred: Pankaj Patel

Step 2: Debug

This is a step I think a lot of inexperienced code reviewers skip over. DEBUG THE F%$*@!+ CODE! For real though, pull the code down, set breakpoints on all of the changes (because you know where they are because you just did a before and after compare on them) and start to debug. I find that it helps me if I just go line-by-line and get an understanding of what each piece is doing.

This is where I really start performing the review. I look for any errors, bugs, or design flaws. I also ask questions about anything I’m unfamiliar with myself. If the developer created Unit Tests I try to either add my own data to those tests or see if I can break them. This helps expose any areas the developer over-looked.

You might be thinking that stepping through each line is not needed or that it’s a lot of extra work but in all honesty it’s not. You can debug a few hundred lines of code in a matter of minutes. Most developers break things out into more lines than what they would ever really need and stepping through that code becomes even easier.

photo cred: Agence Olloweb

Step 3: Feedback

After stepping through every line of code you should be prepared to provide your feedback. When it comes to feedback I find there is really only one good way to do it. Keep it positive and make it suggestive. At the end of the day, the developer who wrote the code has to be responsible for the quality of that code. Often times if you try to force a change in your code review you’ll end up with a You vs Me scenario that isn’t really productive for anyone.

I prefer to start with something positive. I try to take into account the amount of time and effort the developer had to put into their work and look for any design patterns or usage of good programming practices that I can point out right a way. It’s a lot more fun to code review someone’s work when they are using best practices.

For the harder stuff, I try to offer up changes as a suggestion. Unless I see a clear cut bug. If I see a bug or true flaw I try to provide a Unit Test or solid steps to reproduce to help the developer out. After all, we’re all in this together.

If the change is more about design or best practice, then I offer it as a suggestion. I might say, “Hey you could try this technique here to reduce x amount of code” or “If you try this, it can help keep things easier to maintain down the line. Let me know if I can help!” Offering up additional services or help is often a great way to provide feedback.

Advertisements

Step 4: Rinse & Repeat

From there you can send your code review back. Try to capture as much as you can in that first review. It’s much less grueling if you have to go back-and-forth and back-and-forth because you keep only catching one issue at a time. Try to capture all of it, up front, on the first review.

When the code comes back again for a second review. Hopefully all items are addressed and you can pass the review BUT don’t be afraid to go back through steps 1-3. Actually I encourage you to go through them each time, just maybe at a faster pace or a high level. For example, your first pass you should debug every line of code, maybe on your second review you just stick to the areas of change.

Hopefully this gives you a good idea of how to conduct a code review! If you have any personal tips on your best practices for code reviews I’d love to hear them!