|Welcome to the Monastery
On Coding Standards and Code Reviewsby eyepopslikeamosquito (Archbishop)
|on Feb 19, 2009 at 03:34 UTC
I've been asked to prepare some guidelines on coding standards and code reviews in general, across a number of languages used at work, not just Perl. After doing a bit of basic research, I've cobbled together the notes below. To gain some feedback, I'm posting an early draft here.
Note that language-specific coding standards are not covered here; these will be covered in separate coding standards documents, one for each language.
Most of the coding guidelines below were not invented by me, but derived from hopefully well-respected sources; see the Coding Standards References section below for details.
Update: see also Why Create Coding Standards and Perform Code Reviews?
These are some general attributes you should strive for in your code. Remember that code maintainability is paramount.
Design and Architecture
API Design Checklist
For more detail see: On Interfaces and APIs
Layout rules will vary between organisations. These sort of arbitrary code layout rules should be enforced by a tool (e.g. Perl::Tidy).
When should you depend on another CPAN module rather than write your own code?
Comments and Documentation
GUI User Interfaces
Internationalization (i18n) and Localization (L10n)
These domains warrant their own section. However, both these domains can be incredibly challenging. :-) For now, this is just a stub section.
Some Famous Programming Quotes
The two principal types of code review are: formal and lightweight.
Formal code reviews require significant planning, training and resources; they are carried out in multiple phases by multiple participants playing various roles. The most well-known formal code review method is the Fagan inspection.
Lightweight code reviews, having less overhead than formal ones, are cheaper to conduct. The Best Kept Secrets of Peer Code Review book argues that lightweight code reviews are cheaper to perform than formal ones and can be just as effective. The four most common types of lightweight code review are:
Lightweight Code Review Tips
Cited in Best Kept Secrets of Peer Code Review, the conclusions drawn from a lightweight code review case study at Cisco are:
The Seven Deadly Sins of Software Reviews
According to Karl Wiegers, the Seven Deadly Sins of Software Reviews are:
Miscellaneous Code Review Tips
Tool-assisted Code Review
Guido van Rossum's first project at Google was Mondrian, a code review tool. Though he was unable to open source that work, he has since released the open source Rietveld code review tool. An exhaustive list of code review tools can be found at Survey of Code Review Tools.
In addition to tools that streamline the administrative side of the code review process, source code analysis tools can further be useful during code reviews. These tools fall into three broad categories:
Coding Standards References
Code Review References
References Added Later
More References Added Later
Dealing with duplicated code:
Updated 20 Feb: Added new "Design" and "Portability" sections. Updated 3-mar: Added new "Security" and "Internationalization and Localization" sections; added more General Guidelines; added more references. Updated Nov/Dec 2017: Added "OO Design" and "References Added Later" sections; extended "Comments" section to "Comments & Documentation". Aug 2020: added naming scheme for packages and classes. Added new Dependencies section from Writing Solid CPAN Modules. Mar 2021: Moved "Correctness, simplicity and clarity" to first bullet point (see salva's response below). Mar 2021: added "API Design Checklist" section, adapted from On Interfaces and APIs. June 2021: Comments and documentation section: added input, output, or "inout" when documenting function parameters (see Re^2: flower box comments).