Since writing On Coding Standards and Code Reviews, several people have asked me:
- Is it worth it to have a coding standard and to perform code reviews?
After all, you pay an opportunity cost in that time and energy spent on these activities might be better spent elsewhere.
I should have thought about this earlier because it would have helped focus our coding standard effort on tangible business benefits.
To remedy that oversight, I list below what I see as sound reasons for having a coding standard and for performing code reviews.
Why Have a Coding Standard?
Successful software tends to live a long time: bugs are fixed; new features are added; new platforms supported; new versions of the language and its libraries released; the software adapted to new markets. That is, successful software development is a long term activity. If you plan to be successful, you should therefore plan for your code base to be maintained by a succession of many different programmers over a period of many years. Not planning for that is planning to fail.
Put another way, it's the difference between Programming "Hey, I got it to work!" and Engineering "What happens when code lives a long time?". A quick one-off hack is fine if the code only needs to run a couple of times ... but not if it becomes a long-lived critical feature.
Programming is easy, Engineering hard. You need to hire programmers with sound technical skills and domain knowledge, enthusiastic, motivated, get things done, keep the code clean, resilient, innovative, team players ... and then motivate them, train them, keep them happy so they don't want to leave, yet have effective handovers when they do ... a hard problem. Yet to be successful that's what you need to do.
This is the primary reason why you want a company coding standard: to make long term code maintenance easier.
Notice that if you choose instead not to mandate a coding standard, you'll likely end up with an informal one anyway, as some strong personality in your organisation fills the vacuum by evangelizing their own set of pet coding rules.
The goals of a good coding standard are:
- Improved code maintainability. Code that comfortably lives a long time while being maintained by a succession of many different programmers over a period of many years, so that developers and others can understand its construction and intentions and change it comfortably and confidently.
- Improved code quality. In particular: testability, supportability, portability, security, efficiency, robustness, high cohesion/loose coupling.
- Improved development speed. Your developers don't need to make all decisions starting from first principles.
- Better teamwork. Don't waste time with needless debates. Spend your creative energy on things that matter.
- Make it quicker and easier for a developer to move to a different project or team.
- Better performance under pressure. Under stress, people fall back on what they've been trained to do.
- Fewer bugs. Good standards should minimize common coding mistakes.
- Shallower learning curve and useful training for new hires -- if your standard mandates proven, well-known idioms and style from the programming mainstream.
- Higher company IP value.
- The coding standard should be something developers learn from, want to follow, and want to contribute to; it should make their lives easier, not harder.
- The coding standard should be a living document; you need a mechanism for evolving it and for dealing with the millions of lines of old code that are affected by changes to it.
The above list represents real business benefits which should help you decide what to put in your coding standard and what to leave out. My experience here is that shorter is definitely better. The longer your coding standard document, the less likely that it will be read, understood and followed.
Why Perform Code Reviews?
- Find and fix defects early.
- Code review often proves more cost effective than testing.
- Good mentoring/training/learning/team building, especially for new hires.
- Gives broader experience to team members.
- Makes it easier for one team member to maintain another's code.
- Improve overall quality of the code.
- Improve code documentation (code review doco helps explain why the code was done that way).
- Enforce coding standards.
Of course, code reviews are not free and there is an opportunity cost in that time spent reviewing code means less time spent on other activities.
How Can Coding Standards Improve Development Speed?
Mainly in areas of Cross-cutting concern. For example:
- Error Handling.
- Logging.
- Tracing.
- Debugging.
- Security.
- Portability.
- Memory Management.
- Concurrency and Locking.
- Serialization and Persistence.
- Transaction Processing.
- Thread-safety and reentrancy.
- Exception-safety.
- Internationalization and Localization.
- Libraries.
- Documentation. Standard documentation templates. Standard code organisation.
- Naming. Standard abbreviations.
- Unit testing.
- Other testing.
- Code review checklists.
- Build engineering.
- Release engineering.
- Patch engineering.
Update: as noted by gwadej below, style guides should be separated from coding standards. Stronger, I feel style guides should be enforced/automated by a tool (e.g. Perl::Tidy), so as to avoid wasting time in unproductive arguments about indentation, brace placement, and so on.
References
- On Coding Standards and Code Reviews
- On Interfaces and APIs
- Coding Standards from The Art of Agile Development by Shore and Warden
- Best practices, revisited by ELISHEVA
- Cross-cutting concern
References Added Later
- Working Solo and in a Team (How to create High Performing Teams)
- Re^2: Google considers Perl a useful skill (written later)
- Splitting program into modules (asks how to refactor a large chunk of messy inherited code)
- Re^3: Criteria for when to use a cpan module (Titus Winters Talk) (snippets from Titus Winters "C++ as a Live at Head language" talk, cppcon 2017)
- Unix shell versus Perl
- The Joy of Legacy Code (Habitability is the characteristic of source code that enables programmers, coders, bug-fixers, and people coming to the code later in its life to understand its construction and intentions and to change it comfortably and confidently ... is what we want from our coding standard)
- Re: Working Solo and in a Team by hv (2023) - benefits of code review: improved code quality; reviewee and reviewer learning; review documentation helps explain why the code was done that way
- smartbear Best Practices for Peer Code Review
- eBook: Best Kept Secrets of Peer Code Review
- smartbear What is Code Review
- smartbear Code Review Collaborator Tool
Updated Nov 2018: added new "How Can Coding Standards Improve Development Speed?" section. Dec 2023: added Improve code documentation bullet point to "Why Perform Code Reviews?" (thanks hv)