Book Excerpt

Watch-out the programming Pitfalls

Small, frequent code reviews keep your code clean, simple, and tidy. You can avoid the traditionally unpleasant code reviews that involve dozens of developers and require days of preparation (a.k.a. The Mighty Awful and Dreaded Code Review, hereafter referred to as MAD reviews for your reading enjoyment). We’ve found code reviews can be painless when you adhere to the following rules:

• Only review a small amount of code.
• There are one or two reviewers at most.
• Review very frequently, often several times a day.

Your goal is to move toward a habit of more frequent code reviews while not incurring the potential culture shock (or the perceived overhead) of pair programming. Many environments just aren’t ready for that level of interaction; the cost of breath mints alone could break a thriving company! So instead, strive to review your code more often and in smaller chunks.

If a week goes by without a code review, you’ve allowed a lot of time for serious problems to creep into your code. You likely need an outside perspective if you have been working on a tough problem that long. It’s not even that another person knows better; just the act of explaining the problem is often sufficient for you to then solve it (The Pragmatic Programmer calls this rubber ducking).Waiting days before getting a code review (even if it’s just an interim checkup) will probably be a long and painful experience…a MAD review!

To avoid MAD reviews, separate your work into the smallest possible pieces and get each one reviewed independently and committed into the source code repository. Then if there’s a problem with any one area, it’s easily isolated.

Programmers can easily get so caught up in the details of a particular task that they miss obvious big-picture improvements. When you stop to explain your direction and code to another person, you have to break that flow, and you’ll often get a valuable fresh perspective. Sometimes we are so busy creating a road in the woods that we don’t realize we are in the wrong forest, headed in the wrong direction!

Another benefit of segmenting code is that reviewers can more readily understand the code if it’s divided into smaller pieces. In a fast-paced development shop, you may need to have your code reviewed many times in one day. A good rule of thumb, however, is to never work for more than two days without getting a code review. Think of code reviews like breathing. Sure, you can go a few minutes without breathing, but who wants to?

Ideally there will be one review for each feature you add (or for each bug you fix). Holding your code until you have seven new features added and fourteen bugs fixed is a recipe for the dreaded MAD review (not to mention a long, drawn-out, and unfocused effort).

If you’re in the position of rewriting an intricate part of your product and you can’t divide the task into smaller parts, pick one reviewer and have that person frequently do on-the-fly interim code reviews.

You’ll write better code when you know someone else will see it and hold you accountable for it. This issue isn’t unique to developers; it’s simply human nature. Code reviews ensure that at least one other person will look at your work. You’ll know that you can’t take shortcuts in your code with this accountability in place.

Plenty of research shows the effectiveness of code reviews at detecting defects (bugs) in code. In fact, it’s the number-one technique for finding bugs. There is none better. If you haven’t done code reviews consistently, you may be in for a surprise at what you’ll find.

We’ve actually seen variable names like mrHashy (Mister Hashy) for a hash table. However, after a single code review, that developer began to use more relevant variable names to avoid being teased by co-workers. Peer pressure can be painful yet effective.

Rubber ducking (explained previously) is a very- effective way of finding and solving problems. By describing your code to someone, you’ll suddenly realize things you forgot, recognize logic that just won’t work, or find conflicts with some other area of the system. We want you to “talk” to the duck every-time you check in code.

Besides the value in rubber ducking, other developers will spot bugs in your code. Having a fresh, second set of eyes to look over your code will often catch issues that never even occurred to you. You’ll be getting a completely different point of view. Finding bugs in the development shop is always cheaper than finding them when the code is in the field. The return on this small investment is immense.

Code reviews are great for fostering knowledge sharing among team members. After collaborating on the review, your reviewer will have at least a conceptual idea of what your code does and you hope a detailed understanding of it. This has enormous mentoring benefits and helps in code maintenance as well.

Reviews provide a perfect opportunity for experienced developers to pass along code style and design techniques to less experienced programmers. Beyond the trivial technicalities (such as where the brackets go), code reviews give the veterans a chance to advise the greener developers on why one data structure might be better for this situation, or to point out that a pattern is emerging. Quite often, a reviewer will spot repeating code or functionality in these sessions, which can be moved to common base classes or utility classes. Your code becomes refactored before it gets checked into the source code management system.

Reviews also facilitate cross-training on small areas of coding details as well as big-picture concepts. Beyond “coding style,” you are learning to “code with style.”

Code reviews must involve at least one other developer. In practise, it will almost always be just one other developer unless you are creating something interesting or clever that other team members want to learn about. Then feel free to include more developers. Don’t go overboard, though (no more than three to four, tops); too many developers bog down the review.

Do not make code publicly available without a review. Don’t add your changes to the source code from which your product is built until a review has been done. Part of the comments you include with the code’s check-in should list your reviewer’s name. Then, if there are questions about the reason for the code change and you’re not around, there is a second person who should be able to explain it (at least at a basic level).

Never use this code review rule as an excuse to not check in your code. If your company has a source code system that holds only production code, then put your code into a private area until it’s ready. This private area might be a separate code repository or another installation of the source code management system. Use whatever tools you need to get the code off your machine so that when your machine dies (as machines are prone to), your code doesn’t die with it.

Excerpt from ‘Ship It! A practical guide to successful software projects’, by Jared Richardson and William Gwaltney Jr.
Price: Rs 250
Contact: Akbar Shroff
Phone: +919867230571, 022-22070989
E-mail: cbs@vsnl.com
Website: cbs-india.com