Given typical defect densities, any non-trivial design or code is going to contain some errors. Even seemingly trivial maintenance fixes are likely to be defective.

It’s your job as a reviewer to find as many of these defects as possible. If you’re not finding defects, you’re wasting your time on reviews.

That “one simple step”? Remind yourself that there are almost certainly defects in the work product you’re reviewing, and then find them. It’s all about attitude.

Related posts:

1. Who Else Wants Better Short Term Memory? In “Talent is Overrated”, Geoff...
2. 3 Easy Ways to Stick to a Coding Standard When you’re writing python, you...
3. 9 “Must-Have” Tools for Software Teams The items below are useful...

His simple example is the 13-letter word “lexicographer”. To you and I (assuming you speak English and have a decent vocabulary), it is easy to remember. We don’t have to remember 13 letters, we just remember the whole chunk. But when presented with “trgdpxhdewfwm” for 3 seconds, you probably can’t remember more than half a dozen letters.

Another example is that chess masters can recall board positions after being shown a chess board with pieces on it for just a few seconds. They do this by chunking sets of pieces together — almost like “words” — whereas novices will try to remember individual pieces (“letters”).

It struck me that programmers do the same thing when reading and writing code.

The coding standard helps us, by telling us where the chunks are and how to draw the boundaries between chunks.

If you have a coding standard.

And apply it consistently.

When you choose names at random, you destroy your short term memory. You become a crappy programmer, and you drag everyone around you down too.

Quick example in C. Assume you’re writing a small module for checking environmental status.

BOOL isOverTemp();
BOOL isUnderTemp();

int GetCurTemperature();

BOOL env_isOverVoltage();
BOOL env_isUnderVoltage();

Anyone writing this pile of gibberish should be fired excommunicated.

Why?

For starters, I just wrote it, and I can’t now remember which was camel case and which was underscored. Also: which one was abbreviated?

Before you object that this is a contrived example, two points: (1) yes, it is contrived, that’s the point of an example, and (2) I have worked with far worse on an almost daily basis — the example above is fairly tame.

On the other hand, if you know the coding standard has some simple rules — and they are followed uniformly — you can easily remember the function names.

1. Initial 2-3 letter module prefix (“env” for this example).
2. All functions are lowercase with underscores.
3. No abbreviations.

Then we have:

BOOL env_is_over_temperature();
BOOL env_is_under_temperature();

int env_get_cur_temperature();

BOOL env_is_over_voltage();
BOOL env_is_under_voltage();

Now, when you’re writing, reviewing, or maintaining code, you don’t need to constantly refer to the header or documentation to get it right. A simple three-line coding standard just boosted your memory capacity by over 643%.

(In the interest of full disclosure: I made that number up.)

I realize that implementing even this simple three line standard is controversial because all the camel case folks are pulling out big sticks and the underscore people are grabbing rocks. To which I say: just flip a coin and enjoy the extra brain power. Adopt a three-line standard, follow it, and save the curly-brace debate for the next major coding standard revision.

Related posts:

1. 3 Easy Ways to Stick to a Coding Standard When you’re writing python, you...
2. One Simple Step for Avoiding Shallow Reviews It's your job as a reviewer...
3. Open an SSH Tunnel in Four Seconds or Less As I mentioned in a previous...

Why do this? Well, for one thing it makes code reviews easier when everyone follows the same conventions. It also makes maintenance easier.

1. pep8.py is a style checker that enforces the rules of PEP 8. The “official home” (?) at browsershots.org was dead as I was writing this. (Thanks GitHub!) Run pep8.py on your code and it will tell you where you’ve drifted from the standard.
2. pylint is lint for python. It provides more functionality than pep8.py, but is not a strict superset. (pep8.py is pickier about whitespace issues.) Pylint is also configurable to enforce various naming rules. Like most lints, the SNR is pretty low, but you can turn off most of the noise and get a reasonable signal for the things you want to check.
3. Subversion (as well as most other tools) can be configured to run a script every time you check in code. Run one or both of the above tools in the pre-commit hook and bad code will be rejected. (I’d be wary of doing this with pylint unless you’ve got the categories of “noisy” warnings turned off.) I don’t have anything cookbook for this yet, but I’m working on it…

Related posts:

1. Who Else Wants Better Short Term Memory? In “Talent is Overrated”, Geoff...
2. Using Python’s ctypes to Call Into C Libraries The ctypes module makes loading and...
3. Data vs Code I’ll take an array over...

Jason Cohen pointed to an article of his in which he said “List no items that can be automated.” (His emphasis, but I second the motion.)

In the context of the SANS paper, let’s look at five items that should be automated so that no human has to find the defects:

1. CWE-665: Improper Initialization. As the write-up for CWE-665 suggests, you could use a programming language that forces you to explicitly initialize all variables before use. Or, if you’re stuck with something like C, make sure you turn on the warnings in your compiler, or use a static analysis tool (e.g. lint) to verify that all variables are initialized before being used. Tools like Coverity can be very sophisticated in their static analysis.
2. CWE-119: Failure to Constrain Operations within the Bounds of a Memory Buffer. Same goes for this one. First, use a programming language that doesn’t require attention to every tiny little detail of string handling. Failing that, apply static analysis. It’s also worth performing runtime analysis (e.g. electric fence, Purify) with appropriate test cases to verify that you’ve avoided buffer overflows.
3. CWE-404: Improper Resource Shutdown or Release. Even garbage collected languages can have problems with resource release. First, some GC systems have problems with circular references. Second, GC systems are typically worried about releasing memory. You also have to worry about database handles, file handles, and sockets. Configure your static analysis tool to track resources like these so that you don’t have to do it manually.
4. The write-up for CWE-404 also mentions in passing that you should “wash your garbage before you dispose of it”. This is useful for two reasons: first, an attacker won’t have access to the contents of previously used memory, and second, it often makes debugging memory problems easier if you write a known value into freed memory. (I modified malloc() at my last job to write 0xcacacaca into freed memory so that we would know right away when someone stepped on a turd, um, I mean used freed memory.) Configure your libraries to shred objects before you free them and you won’t have to worry about it on a line-by-line basis in the code you review.
5. CWE-362: Race Condition. I’m typically worried less about security than the nightmare of isolating and debugging race conditions. I haven’t seen any tools that detect race conditions well, but Coverity does a decent job of telling you when you’ve mishandled a race condition in a couple of cases: first, it warns you when you fail to release a lock, and second, it warns you when you access a resource that is statistically accessed from within a lock. So you still have to beware of race conditions (at the design level is the bset place to find these), but there is an option for finding tedious errors in the mechanics of dealing with races.

And now I’m going to throw out everything above.  Remember that the tools are built to detect common errors. If it is really important that you find a certain class of bug, put it on your checklist. In fact, if it’s super critical, make it a checklist of length one. For example, I’ve gone over codebases with the single-minded focus of finding race conditions. When you perform a review like this, it’s amazing how many defects you might find in areas that you never suspected.

Related posts:

1. One Simple Step for Avoiding Shallow Reviews It's your job as a reviewer...
2. Who Else Wants Better Short Term Memory? In “Talent is Overrated”, Geoff...
3. An Interesting pid File Race ISC’s dhcpd uses this code...

Why A Review Checklist is Essential

Most (all?) experts recommend the use of a checklist for performing design and code reviews. It’s more effective to ask a set of questions about the item being reviewed than to simply stare at a bunch of code looking for problems. The checklist focuses your attention on aspects that are most important.

If you want to perform a broader review, develop two or three checklists with different foci and give the lists to separate reviewers. The defect lists from each reviewer will have less overlap than if you gave everyone the same list.

What Your Review Checklist Should Look Like

The following advice is partly based on advice from “Software Inspection” by Gilb and Graham. A good checklist is a list of questions. For practical purposes, I’m strongly in favor of a checklist that does not exceed one side of a printed page — at normal font size. For me this means a checklist of about 15 items, 20 as an absolute maximum. Remember, we’re focusing, which means looking harder for just a few types of items. If you’re using online checklists, I’d extend this to mean that it should fit on the screen without scrolling. Either way, I don’t think you should have more than 20 questions or so at the max. Fewer is probably better, more is too overwhelming.

Checklist items are yes/no questions. They should all be phrased such that a “no” answer means something is broken.

When reviewing, proceed through the entire item under review (the entire code listing or design) with each question. Don’t work linearly, this is a horrible way to review code. I prefer to review on paper, simply because I can make little notes and marks all over the paper as I go through it. For the first question, you might work mostly front-to-back. Then the second question might send you backwards through the code. After a couple of passes over the code you have some familiarity with it, so the third question might send you straight to a location that has potential problems.

How To Choose Questions for the Review Checklist

Since the whole point of the checklist (and reviews in general) is to find defects, the questions should focus on finding the highest value defects. Why waste valuable checklist real estate on a question like “Does the code conform to formatting conventions?” Duh. If your team has a formatting convention, and you look at a piece of code that doesn’t conform, it’s going to jump off the page and bite you in the nose. You don’t need a checklist question for this!

Back to the specific problem at hand: security errors. SANS has done a great job of sifting through tons of security errors and boiling them down to the top 25. We could probably develop a 100 question review checklist from their Top 25 list, but it would be too big to be usable. So let’s focus on the most important for our application.

For this exercise, our application is a blog like Wordpress but much simpler: no plugins, no comments, single author. This is not a hosted application like Blogger, so we are less concerned about vulnerabilities like cross-site scripting, SQL injection, and OS command injection. We do need to make sure that only the author is allowed to post, so let’s look at the “Porous Defenses” category.

• CWE-285: Improper Access Control (Authorization)
• CWE-327: Use of a Broken or Risky Cryptographic Algorithm
• CWE-259: Hard-Coded Password
• CWE-732: Insecure Permission Assignment for Critical Resource
• CWE-330: Use of Insufficiently Random Values
• CWE-250: Execution with Unnecessary Privileges
• CWE-602: Client-Side Enforcement of Server-Side Security

The entry for CWE-285: Improper Access Control lists the following for prevention and mitigation:

For web applications, make sure that the access control mechanism is enforced correctly at the server side on every page. Users should not be able to access any information that they are not authorized for by simply requesting direct access to that page. One way to do this is to ensure that all pages containing sensitive information are not cached, and that all such pages restrict access to requests that are accompanied by an active and authenticated session token associated with a user who has the required permissions to access that page.

Here are some straightforward checklist questions we can extract from that description:

1. Does every administrative page enforce access control on the server side?
2. Are unauthenticated (anonymous) users prevented from accessing administrative pages?
3. Is caching disabled for administrative pages?
4. Does every administrative page validate the session token properly?

Now you can go walk through your design and/or code to verify that you can say “yes” to each of these questions.

If you found this post helpful, subscribe to The Daily Build to get updates as they are posted. Thanks!

Related posts:

1. One Simple Step for Avoiding Shallow Reviews It's your job as a reviewer...
2. 9 “Must-Have” Tools for Software Teams The items below are useful...
3. Using Python’s ctypes to Call Into C Libraries The ctypes module makes loading and...

Through some odd coincidence these posts crossed my path recently:

• Check In Early, Check In Often [comments here are especially good]
• Best Practices for Version Control
• 5 SVN Best Practices
• Continuous Integration is an Attitude, Not a Tool

What I got to thinking about is that version control is one of the foundation tools in your development process. It enables many other processes and practices. The posts above make great points, but I’d like to put them in the context of the overall process. (I’ve also given some thought to the conflicting advice given, again in the context of the forest instead of the trees.)

1. Use version control! If you’re not doing this, you should get out of the profession now.
2. Check in often. This is frequently given advice, but I feel it’s often given out of context. Jeff Atwood includes a quote from AccuRev founder Damon Poole:
   My rule of thumb is “check-in early and often”, but with the caveat that you have access to private versioning. If a check-in is immediately visible to other users, then you run the risk of introducing immature changes and/or breaking the build.
   (My emphasis.) “Private versioning” means a private branch: you can check in without affecting anyone else (see #8). But even with a private branch, consider Salvatore Iovene’s advice: “SVN is not a backup tool”. He makes the point that you shouldn’t check in before you go home just because it’s the end of the day. Instead check in when you have a logical unit of work (e.g. everything compiles, most of the tests pass but you have to make some experimental changes to finish the feature or perform debugging, etc.). The danger is that if you have to revert because you’ve made some disastrous changes, you won’t have a sane state to revert to. Final point: Salvatore also reminds us that some tools don’t commit to a central repository by default (git, darcs, etc), so checking in doesn’t replace a good backup.
3. Put everything in version control. This is a key enabler for continuous integration (CI). James Shore has several great posts on CI. I think he under-emphasizes the need to check in everything necessary to build. First, it should be easy for a new hire to pull down a source tree and immediately get a good build. It makes life easier for them and for you. Second, your CI server should be able to do the same thing. If someone upgrades one of the tools locally and the build depends on this then the integration build should break. The tool upgrade must be checked in so that everyone picks up the change.
4. Don’t break the build. [When I say "build" I mean "build and tests". It's unfortunate naming but I think this is the way the term is used by a lot of people.] This is a promise that the team has to make to each other: “I will not break the build.” What it means is that every team member agrees not to check in code to the trunk that does not build and pass all tests. If you have jerks on your team that constantly break the build, ask them to play by the rules, and if they can’t then get rid of them because they’re dragging you down.
5. Check in bite sized chunks. Too big and you’ve probably been working too long: did you go dark? Large checkins are also harder to review well, so quality will suffer. If a given feature is large, create a branch and continue to check in bite sized chunks (see #6).
6. Branch, but only when needed. If you don’t have bite sized chunks, or if more than one person needs to work on a feature that can’t go into the trunk, create a branch. When you have a branch, it is critical to update (or merge, or pull, whatever terminology you prefer) into the branch from the trunk on a regular basis. Integration will be a nightmare if you don’t. When the code on the branch is mature enough, merge (or push) it back to the trunk. (Tip: it doesn’t need to be perfect, it just shouldn’t introduce regressions into the trunk.) If more non-bite-sized work is needed on the feature, create a new branch and repeat the process.
7. Check in when you’re ready. But not sooner or later. This should be obvious, but some people don’t seem to get it. If you check in before you’re ready, you break the build (and your promise to your team members). This can stop your entire team dead in their tracks! If you wait too long, you’ve lost the opportunity to get rapid feedback on your work. This practice enables continuous integration. It relies on having work broken down into bite sized chunks (see #5).
8. Use private versioning. Private versioning means that each developer has his own branch (or even multiple branches). With a VC tool like AccuRev, this is automatic: every tree has an associated private stream (branch) on the server. With distributed VC tools like git, this is also automatic: everything is private until you push/pull to the central repository or another developer. It can be simulated with other tools but requires a bit more effort. This allows individual developers to maintain several versions of their work before they are ready to share with the rest of the team. It also allows a developer to keep a sane version of code before merging in changes from the trunk. (If the merge becomes a disaster, he can discard the merge results and go back to the sane version without much effort.)
9. Update/merge/pull regularly. This also seems obvious, but again not everybody gets it. I mentioned it above as part of branching, and it’s especially important if you’re using private branches. You must merge from the trunk to your private branch/workspace/sandbox regularly. If you have private versioning, this is low risk because it’s easy to revert a bad merge. (These two practices create a self-reinforcing virtuous cycle!)
10. Train your users. I’ve worked in shops where it seems like only half of the team understands anything beyond “checkout, update, checkin”. Everyone must know how to perform daily duties like checkout, checkin, update and merge from trunk, merge from private branch to trunk, how to navigate history, perform diffs, etc. Everyone should know how to perform less-frequently-needed duties like odd sorts of merges – cherry picking, etc, though this is maybe less important.
11. Use a common project structure and naming convention. Thanks to Anders Sandvig for this bit of wisdom. I wouldn’t have thought to include it in VC best practices but it makes sense to list it here. A common project structure makes it easier to add every project into the CI server. For example, I’ve used the CI server to enforce the rule that every project must provide a $BUILDROOT/build script that runs the entire build. (The server also enforced placing tests in $BUILDROOT/tests, list of images to be published in $BUILDROOT/MANIFEST, etc.) This also makes it easier to move staff from one project to another.
12. Enable checkin notifications. This is typically seen as an email from a post-commit-hook (or whatever your tool calls it). The checkin notification can also launch CI build. Ideally, the notification will tie each checkin back to whatever issue/defect/task/project tracker you’re using.
13. Write good checkin comments. This makes notifications worthwhile. Remember that VC is a communication tool as much as a time machine! I’ve had several experiences where reading someone else’s checkin comment has spurred a discussion that either causes them to rework their bug fix or it has caused me to change course on something I’ve got in progress.
14. Perform atomic checkins. – When it’s time to check in, don’t do ten different checkins for the ten different files you modified! They all belong together as a logical unit. This makes merging easier. It prevents the CI server from running multiple build and test cycles needlessly (and from reporting spurious breakages because it picked up half a change). This makes history easier to understand when others look at comments. This is part of training, and is reinforced if you expect all developers to merge regularly. (On the theory that merging is easier when checkins are atomic.)
15. [Advanced practice.] Use a holding area. – Instead of checking in to trunk, developers check in to a holding branch (call it “pre-integration” or something similar). You perform code review and run integration tests on that branch. When review has approved the changes and the tests pass, promote (merge) the change from the holding area to trunk. The rest of the team pulls (merges) from the trunk, which is guaranteed safe. I’ve also seen the use of a two-level holding area where the first level is for review and the second level is integration test. This is the default if you use private branches (#8) and perform code reviews out of the private branch before integrating (#16).
16. Perform reviews on checked-in code. This is so much better than manually gathering changes and emailing patches around. (Though tools like git have optimizations specifically for eamiling patches around.) This is easy if you’re using private branches since you can request a review before integrating. Some code review tools enable this.

Related posts:

1. 3 Easy Ways to Stick to a Coding Standard When you’re writing python, you...
2. Insist on Automatic Tests At some point your team...
3. 9 “Must-Have” Tools for Software Teams The items below are useful...

Design Review

I do a handwritten (paper) design. I like to design offline — I find that this forces me to do two things. First, to slow down and get it right. Second, to stay at about the right level of abstraction instead of drilling down into too much detail. When I’m done the paper design, I review it against a checklist that I build from mistakes found in downstream phases. My design reviews catch about 70% of the mistakes I make while designing. I’d like that to be higher, but it is definitely worth taking the time to do it. This isn’t specific to Django or Python, I do this for all projects.

Written Test Plan

After design review is done, I write (on paper, informally) a unit test plan based on the design. This is only possible when the design is at a low enough level that you can know what the general flow of control looks like through each method. I aim for full branch coverage in my unit tests. This doesn’t mean it will be “fully tested”, but at least I’ll have exercised most of the code. I usually find (and fix) a couple of defects while writing the test plan. This is also something I do for all projects.

Code Review

After I’m done coding, and before I run any of the code, I print it out and review it offline. The following bash alias is helpful (prints 2-up):

# usage: py2pdf OUTPUTFILE INPUTFILE(s)
py2pdf ()
{
    out=$1;
    if [ -f $1 ]; then
        echo $1 exists, aborting;
    else
        shift;
        echo $*;
        a2ps -A fill -E -2 -C -o - $* | ps2pdf - > $out;
    fi
}

It’s controversial, but I like the advice from Watts Humphrey in the PSP: review code before compiling (or in this case, before running any unit tests since there isn’t really a compile phase). It forces me to be much more thorough looking for defects since I know that python hasn’t filtered anything out yet.

To review the code, I use my checklist which is built in the same way as the design review checklist. I also use the test plan, walking through the code with each test case to see if there are any defects that testing will expose. It’s better to fix these now instead of waiting for the unit test to find them. Two reasons: First, it’s faster because you can see what the problem is. Second, you may notice something that the unit test won’t catch for whatever reason — maybe you don’t end up including the right data pattern to catch the defect. Code review is a generic defect removal practice.

Unit Test – XHTML Validation

Again, this seems to be controversial though I don’t really understand why. Some people don’t think valid XHTML is worth much. I validate because I want to make sure that my generated content isn’t horribly broken, and — just like compiler warnings — you either validate cleanly or you don’t validate at all. As soon as you start ignoring “a couple of silly errors” everything goes downhill.

I wrote an XHTML validator middleware for Django but I haven’t yet used it on this project. Why not? Well, I was trying to use Dojo as a javascript library, and it’s not possible (or at least not easy) to write valid XHTML while using Dojo widgets. So I had to write some special code in my test harness to strip out all of the Dojo garbage and then validate the result.

I’m using jQuery now, I’m much happier, and I suspect I’ll be able to validate using the middleware on my next iteration. (Which involves ripping out the Dojo false starts.)

Validation is generic for any web project. The middleware is specific to Django.

Unit Test – Test Plan

I implement the written test plan using PyUnit, the Django enhancements based on PyUnit, and Selenium for browser-based testing.

My test plan usually generates a lot of test cases (a recent app had over 100 test cases for about 800 lines of Python, 700 of Javascript, and 200 XHTML). So I like to keep them in separate files in a “tests” directory in each app. One trick that I use is to implement a suite() function in my APP/tests/__init__.py. The suite function globs “APP_tc_*.py” and sorts them by time stamp, most recent first. This way if a test is failing I can make sure that it runs first when I fix the problem and rerun the suite. The other part of the trick is to add an optional argument to the globbing/sorting function that limits the number of test cases returned. So when I need to rerun a test a few times to fix a tricky problem, I don’t have to wait for the entire suite to run to get the results of the test-under-development. This is all highly specific to Django development.

Unit Test – Pylint

This is still experimental for me. Pylint generates a lot of noise. Most of what it reports is legitimate, but about 90% are minor (i.e. not-user-impacting) defects. I’ve had to spend a fair amount of time tuning the report parameters to stifle the noise. The most time consuming part so far has been filtering out results from the test code. I’d like to figure out a way to make pylint skip the test files but there doesn’t seem to be a setting for this. On the bright side, it nagged me into making some of my test code more maintainable. Obviously pylint is specific to python, I use other lint-like tools for other projects when the signal-to-noise ratio is high enough.

Unit Test – jslint

I’m a javascript novice, so jslint has been helpful in ferreting out problems that I would not have caught through testing. As I let the feedback from the tool and testing form better design and coding habits/patterns, the signal-to-noise ratio may drop so that this is less effective.

Related posts:

1. One Simple Step for Avoiding Shallow Reviews It's your job as a reviewer...
2. 3 Easy Ways to Stick to a Coding Standard When you’re writing python, you...
3. Who Else Wants Better Short Term Memory? In “Talent is Overrated”, Geoff...

• Codestriker Open source, web based, written in perl I think.
• Code Collaborator Commercial.
• Review Board Open source, web based, appears to be python/Django.
• Rietveld Open source from Google. Guido van Rossum’s 2nd pass at a code review tool. You get three guesses on the implementation language…
• Crucible Commercial from Atlassian.

Bottom line: don’t try to do this by hand, you’ll be wasting a bunch of time packaging patches and tracking defects when a tool can do it automagically for you.

Related posts:

1. 9 “Must-Have” Tools for Software Teams The items below are useful...
2. Data vs Code I’ll take an array over...
3. If the comments are ugly, the code is ugly If the comments are ugly,...

I tweeted this article on Five Reasons to Do Code Reviews from CIO.com last week,and realized that there are much more than the five reasons they give. So I came up with 20 more over the rest of the day. This is a collection of those tweets, with a little more detail given here.

Code review reason 1: Feedback comes back fast enough to give you whiplash. Since code review is done after coding and before integration or system tests, developers don’t have to wait as long to get feedback on code quality. By providing specific, timely feedback, developers can adjust their coding practices to avoid common mistakes.

Code review reason 2: Find more bugs than testing alone. This is obvious: Testing finds bugs. Code review finds different bugs. When combined they find more bugs than you would otherwise remove before shipping to customers.

Code review reason 3: A million monkeys sometimes produce valid syntax, even if it doesn’t make any sense. Compilers can’t catch this. Sometimes you’ll make a syntax error that produces valid syntax so the compiler can’t catch it. The classic here is in C, = (assignment) versus == (boolean equality operator); in this case most compilers can issue a warning but there are other examples. A code review will catch this error quickly, but finding this during testing can be hard to track down.

Code review reason 4: Find and kill bugs where they live, instead of finding turds and having to track them back to the nest. When you get defect reports from a code review, you have in-hand the exact line number and problem description. When you get reports from system test or (horrors!) a customer, you get — at best — a reproducible set of steps to trigger the bug. It’s then up to you to work backwards to the actual defect in the code, which is often time consuming, especially since the code may have been written weeks or months earlier. (See reason #1.)

Code review reason 5: Indoctrinate the n00bs. Code reviews are an effective training tool. First, new software engineers who participate in code reviews get to look at code produced by other engineers and thus get a feel for the coding standard and documentation style. Second, inexperienced engineers will get feedback on their code before they have a chance to infect the system with inferior code. (Because we all know that the code we wrote 10 years ago probably sucks — unless we were fortunate enough to have it reviewed by more senior engineers. If you haven’t already been coding for several years, keep in mind that everything you’re writing today probably sucks but you won’t be able to acknowledge that for another few years; see reason #6.)

Code review reason 6: Uses developer egos to boost quality of code from the beginning. The theory here is that because developers know their code is going to be publicly scrutinized by a group of peers, they will take extra care in coding to avoid the embarrassment caused by having others find all kinds of bugs in their code.

Guest contributor @kyletolle: Code review reason [7]: Explaining code makes sure they understand it well. Will fix the “Uhh, b/c I always do it that way” remarks. After you have to answer this question a few times during a review, you’ll probably ask the question of yourself while coding. (See reason #6.)

Code review reason 8: Makes testing go faster. Heck, it makes the entire development cycle go faster. There are multiple root causes for this. First, since code review finds and fixes defects at the site of the defect (see reason #4), less time is spent fixing these defect. Second, fewer bugs are found by testers so they spend less time writing up issues and the engineering team spends less time tracking and managing issues. Third, testers don’t have to re-run regression tests so many times because fewer release candidates will be needed.. Last, it is less likely that testers will be blocked waiting for fixes to bugs.

Code review reason 9: Fewer angry phone calls means happier tech support staff. Proof: Fewer bugs in shipping code (see reason #2). Customers not disrupted by bugs as often. They don’t get angry as often. So when they call, it’s with songs of praise. QED. (Ok, maybe that singing part isn’t true, but you get the picture.) To prove this from another angle: if you’re spending less time fixing bugs, you can spend more time implementing features that customers are requesting.

Code review reason 10: (Anti-reason) You’ll pay more sales commissions because you’ll be selling more product…wait, that’s a good thing! When customers sing your praises because your product is so reliable, it’s easier both to sell to new customers and to sell more product to your existing customers. Sure, your sales commissions might go up, but I’ve never really heard anyone complain about this too loudly.

Code review reason 11: There are tools that reduce the annoyance factor of old school review processes. After I tweeted this, @kyletolle asked for some recommendations. I will follow up this post with several tools that I’ve found. Stay tuned. (Look at my timeline starting here for now).

Code review reason 12: There’s zero risk. Even not-super-effective reviews beat testing. If I spent a little time I could probably dig up some published research to back this up. But my personal data says my personal code reviews are about four times as effective as unit testing. So even if I perform a half-hearted review, I’m still going to be more effective than testing. (See reasons #2 and #4, also keep in mind reason #5 which doesn’t have an immediate measurable effect.) There might be data out there that says code reviews are a waste of time. Flying reindeer might also exist.

Code review reason 13: (Anti-reason) Testers bored from not finding as many bugs… Oh yeah! They could focus on stress/perf tests. This would be a good problem to have…

Code review reason 14: Reviewing code is good practice for reviewing code. You’ll get better. Your team’s review effectiveness will improve over time. This means that the long term risk of failure is even lower than the short term risk (see reason #12 for why the risk of failure is zero or very close to zero).

Code review reason 15: It’s a great way to build a really useful code review checklist. This is kind of stretching, a useful code review checklist doesn’t really matter to the customer. (I should probably come up with a couple of bonus reasons to account for the “artificial fillers”… Hey, I tweeted this during the 3pm slump before my afternoon cup of tea.)

Code review reason 16: Out on a speculative limb: better staff retention because developers spend less time fixing annoying bugs. I’m not sure about anyone else, but I’ve stayed at a job that was otherwise not-so-great because of the quality of the team I was on and the people around me. Being part of a well-oiled machine feels good. It’s motivating to go to work everyday knowing that you’re going to produce a high quality product and your coworkers are there to back you up.

Code review reason 17: Reduces schedule risk because product quality is higher as it enters downstream phases. Your testers won’t get blocked as much (see reason #8) and testing won’t drag out. Since you get feedback relatively early in the schedule (see reason #1) you have a good idea of how long testing will take.

Code review reason 18: Feedback (especially from peers) at the source level means you will stop making the same mistakes over and over. (See reason #6.) This also stems from the fact that each engineer will have data in-hand about the types of defects he makes and he can come up with ways to prevent this defect from happening to begin with. And this is really when the magic occurs: when you can start thinking about preventing entire classes of defects.

Code review reason 19: Improves the quality of documentation / comments as well as executable code. (See reason #7.) Developers will include better comments to avoid having to answer too many questions from reviewers. If reviewers are looking for inconsistencies between comments and code, this is extra motivation to make sure that code documentation is up to date. Lastly, I suspect that overly complex code will become scarce since this will be scrutinized and questioned more than simple code passages.

Code review reason 20: Customers won’t find as many bugs in their soup. This is maybe redundant to reason #9, but helping customers is why we exist, right? So I’ll allow this one to stand and — like I said above — I’ll work on a couple of bonus reasons to add to this list.

Related posts:

1. One Simple Step for Avoiding Shallow Reviews It's your job as a reviewer...
2. Data vs Code I’ll take an array over...
3. 9 “Must-Have” Tools for Software Teams The items below are useful...