Second principle of code review: write an ode to the code

<< Previous Article: 'The First Principle of Code Review: Check Yourself at the Door'

Stop me if you heard this one. You have written a hundred lines of code. You pass it off to a code reviewer. He tears it to ribbons.

He tells you to restructure some conditionals. He tells you that an algorithm would be better written another way. He tells you to use different classes than the ones you are using.

Then you ask him if he knows what the code does. And he doesn't.

As autistic coders, we are rarely so bold as to challenge the reviewer about his knowledge of what our code does, and we rarely ask this simple question.

But we should.

And, when you are reviewing someone else's code, you should be asking the same thing to yourself: 'What is the purpose of this code?'

Above all else, a code review should be used to determine if you have written understandable code. Given the comments, given the structure of the code, given the flow of control, are you able to say back to the coder what his code does?

If you can't, then one of two things is true:

1. The code fails the review
2. The code reviewer fails the review

 In either case, however, the code review should come to a full stop. There is no point in critiquing code whose purpose you don't understand.

There is no point in giving pointers when you don't know the point of the code.

Make sure you can briefly describe the purpose of the code. If you don't understand what it is supposed to do, how do you know it's does what it's supposed to do?

If you don't understand why it is structured the way it is structured, how do you know if your structural suggestions are correct?