Home > Articles > Data > SQL Server

SQL Server Reference Guide

Hosted by

Transact-SQL Code Reviews, Part Two

Last updated Mar 28, 2003.

In Part One of this series, I explained what a code review is, what it is used for, and why you should implement one. If you are just joining this series, take a few minutes and check that one out first. This week I’ll finish up the topic and explain some practical tools, processes and steps you can take to do that.

Recall that the primary reasons you need to perform a code review involve four main areas:

  • Finding and correcting errors
  • Fostering learning
  • Increasing team-building
  • Distributing “tribal knowledge”

I’ll refer to those goals throughout this article.

Process

To start your code review process, it needs to be important to your organization. It’s going to take time — extra time — that nobody in the organization feels they have. Last week’s article should go a long way towards helping you make it important.

But for the process to work, and not be just a one-time event — it has to be something that you perform regularly. It’s going to take some buy-in and discipline on the part of everyone on the team, so there are a few things you can do as an organization to make that happen.

Baking Code Reviews Into the Culture

The first thing you can do to ensure that a code review gets done is to make it part of the check-in process for code. I’m assuming you have a check-in process, of course, so if you don’t you may need to back up and ensure that you’re doing code-signing, unit tests and the other steps required in any standard development shop. The code review should be one of the checkboxes on this process, so that no developer can check in code without a review, period. At first, this will become a blocker — and you should keep it that way. Blockers get dealt with quickly, so hold your ground. After a while, it will become something you just make happen.

The next step you can take to keep the momentum going for the code review is to spread the load as much as possible. In other words, don’t make just one person responsible for looking over everyone else’s code. In fact, even a junior member of the team can look over another person’s code. I’ll explain some tools to help them do that in a moment. In fact, one of the goals of a code review — learning — is often best accomplished when a junior member of the team looks over other people’s code. The point is, when each person spends a small amount of time on the process, it tends to feel more fair and takes less time — both of which ensure that your team will continue to do it.

Finally, keep it professional. Writing a comment that states “What were you thinking? This is awful!” isn’t helpful at all, and will only serve to alienate another person. The point is to being everyone up to a high level of skill, and to ensure the code is the best it can be. So put the ego aside, keep your smart remarks and witty repartee to yourself, and make constructive, objective comments. Keep in mind, this might be the first time someone has gotten this kind of feedback, so be technical, specific and professional in your comments.

Now let’s examine some of the practical steps of the process of a code review, starting at the point where you have been given a set of code in a script to review. Since I’m directing this tutorial series to data professionals, these steps will be a mix of things you see in a high-level programming language and information specific to Transact-SQL.

Practical Steps

Begin the process by establishing who will do the code reviews, and a window of time to get them back to the original submitter. You’ll also want to decide if the code Is re-reviewed or checked in after the corrections are made.

To expedite the time, use a checklist. Determine the “target areas” you want to focus on — as time goes by, you’ll widen this list, but here’s a quick rundown:

General Refactoring is the most difficult and time-consuming area to consider, so you should work up to that. Your first set of code reviews should focus on the functionality, then security and then performance. Once you’ve covered those, then you can start evaluating the rest of the code. Again, this can be useful even if the review is done by someone that is not as expert in an area as the person being reviewed. In fact, it’s a great way to learn. Don’t be afraid to ask questions, even if you think the person you’re reviewing is better than you at something.

Mechanics and Tools

You should set up a standard format for code review comments in the T-SQL file you get for review. I recommend block comments, with a standard way of representing a review comment, who is making the comment, and when. Here’s something you can paste into SQL Server Management Studio (SSMS):

/* Code Review: <ReviewerName, SYSNAME, ReviewerName>
Date: <DateReviewed, SYSNAME, DateReviewed>
Status: <Status, SYSNAME, Open>
Comment: 

*/

Save that in the clipboard, and then paste it wherever you want to make a comment. Add your comments after the “Comment:” part, then press Control-Shift-M when you’re done and add your name and the date and press the OK button.

When you return the code to the originator, they can press Control-F and search for:

Status: Open

to find the items you have commented on. It’s your choice whether or not to leave the comments in-place in the code or remove them. In compiled code, the comments aren’t normally seen by the public, but T-SQL is often stored “in the clear” in a file, so it might be best to remove them when the correction is made.

There are other tools available. In SQL Server Management Studio, if you’re using a “Solution” for your T-SQL code, you can use Bookmarks to annotate the code. Press Control-K and then Control-W to show the bookmark window. From there, you can click the “Add Bookmark” icon to set a line-marker and some text. Bookmarks can be searched, edited and so on, but you will need to do this in the context of a project and solution in SSMS to be effective, so this is less useful if you’re delivered scripts or just statements from a developer’s C# or Java code.

One of the easiest and most universal tools is just to use your favorite text editor to record your comments. Many of them have the replaceable parameter feature as I described for SSMS, but you’ll need to check their documentation to see the process for that tool. The general idea is to add a comment placeholder in a standard way so that the person receiving the review can locate it quickly and knows that it is still current, not an older closed out comment.

There are also formal tools that facilitate the review, but most of them are focused on languages like C++ or C#. If you have one of those tools (check with your developers) just make sure they include you in the process and train you on what they do to perform the review and the routing.

There is a code review book available, but from one of these tool vendors. It does have some interesting whitepapers, though: http://smartbear.com/best-kept-secrets-of-peer-code-review/.