Code Review Checklist

Here's a checklist for code reviews (in any language).

1) Would the logic be understandable by a developer of average ability proficient with other programming languages but not this one?

If it uses language features or obscure design patterns that are "clever" without good reason (e.g. something needs to have the maximum performance), then it won't be maintainable and someone will replace it or add to it badly. We've all seen code written by someone who has just read the "Design Patterns" book and wants to use all of them. If you want to use the latest trendy language features, think about if someone in 10 years time will know about these of if they will have fallen into obsolescence.

When reviewing code, thinking about this will make long term maintainability easier. It may result in some discussion about which language features and design patterns should be used and standardising on these will mean everyone understands each other's code better.

2) Are properties nouns and methods verb noun phrases.

If properties are not nouns and methods not verb-noun phrases, then it's a sign that these haven't been thought about carefully and the code will be more difficult to maintain.

When reviewing code it's easy to overlook this, but very quick to check.

3) Is there an obvious way of testing each method.

Of course we all know all methods should have unit tests but in the real world this isn't always possible. However, if there isn't one and it isn't obvious how to write one, then the method could probably be expressed better in a different way.

When reviewing code, if you can ask "how will this method be tested" you can better follow the logic. If you can't answer this question then there are more likely to be complexities that aren't picked up until it's too late.

4) Do the names of properties, methods and classes match the names used elsewhere in the organisation?

If the names of objects are different (e.g. your code refers to a regular customer and the business a star customer), then it will be harder to explain what you are doing and more likely that requirements will be misinterpreted. It's a good idea to document these in a wiki to have a single point of reference for these.

This also means if you are working on a method, you can say "I'm working on x in class y", and someone who knows your business area but who is not a developer know would know what you are talking about. This would improve the trust between developers and domain experts.

When reviewing code, thinking about this will help you understand the business domain and make you better able to communicate with them and get accurate requirements in future.

5) Is the total complexity of the system affected as little as possible? (I would define this as the number of classes * average size of each class * the total number of other classes a class has to know about).

This means if you're creating a new function that means the class it is in has to know about 3 more classes than before, the system is more complex as there are more dependencies between classes.

When reviewing code, if you think about this and rewrite if necessary it will reduce the numbers of possible points of failure and mean that testing is more likely to pick up problems before anything goes live.

Characteristics of an effective programmer.

A lot has been written on what makes a great programmer.
I'd like to write about what makes an effective programmer. The two can be different.


I would say the characteristics of an effective programmer are as follows:

• 1) Do you know and care about how the application you are writing will be used, and do you have opinions about how to make it better?
• 2) Do you know about new technologies, can you recognise those that should be adopted in your current projects and can you explain them convincingly enough to get them adopted?
• 3) Can you maximise tha amout of code not written, through efficient design, reusing things that have been written before and eliminating unnecessary requirements?
• 4) Can you recognise your limitations and mitigate these, e.g. by understanding where you need to learn something new or code defensively, and where to get help from others?
• 5) Can you design and write code that can be maintained in 10 years time by someone of average ability, when tools and programming languages have moved on?
• 6) Do you understand more than just code, e.g. databases, infrastructure and can you use this understanding to make it more likely a project will be stable and reliable when it is live?

Do you agree?

Planning poker with Return on Investment

A lot has been written on Planning Poker as part of an agile approach to developing web sites.

I have a new take on this - Planning poker with return on investment. I'm sure we all agree that things that give a lot of value with a small amount of work should take prioriry.

This would work as follows:

The stakeholders would divide into two groups, business people and developers. Business people would use planning poker to estimate the likely return of a proposed development in "return points". Developers would at the same time estimate the likely investment in "story points". "Return points" would likely be related to the amount of money the proposal would make. "Story points" would be related to the number of days development.

You can then divide return by investment to get a priority.

• If return is small, investment big, it's probably best to forget the proposal.
• If return is big, investment is small, it's a no brainer and should be done.
• If return is small, investment is small, it's a medium priority.
• A problem occurs if return is big and investment is big. This suggests there is a risk involved. To reduce the risk, the proposed development should be divided into smaller chunks.

Feedback loops

Mark Needham describes overcompensating in feedback loops.

This reminded me of something from my control theory course at university many years ago. If you are not in a desired state, you should make changes that are a percentage of the difference between your current state and the desired state. You will gradually converge towards it, and not overcompensate for any sudden changes.