Code Reviews: Best Practices



Friday 25 February

15:20 - 16:00 Maintenance Block

Lecture 6

Code Reviews: Best Practices

Gerhard Brandt
This lecture addresses the following questions
How to write code that's readable and understandable ?
Which tools can you use to make this easier ?
How to understand already existing code ?
Starting points for this lecture:
Other people have engineered code for you.
It's your honor to adjust this code where it shows
suboptimal behaviour ( = fix bugs )
You learn from their ingeniosity and apply your experience
as you and others contribute new code
1 Reading existing code
2 Adding new code

Part 1: Reading Code
Approaching a foreign body of code top-down:
Read it in increasing level of detail
Read File/Directory Structure
Recognize Structures
(like Design Patterns, Interfaces, Libraries, makefiles)
stay on top - dive only as required!
( = don't try to read 100k lines of code from the beginning to the end )
* High-level Orientation in an unknown body of code
Command line tools
Code Browsing
Documentation and its Generation
* Use the command line, like: Simple heuristics
* cvs: Watch what happens during checkout
* ls: directory structure
* wc: size

* Code Signatures
Condense code to structural elements: {} , ;
ref: Cunningham W., OOPSLA 2001 Software Archeology Workshop
* Code Browsing:
* ViewCVS
Real-time access to CVS
View Changes, Diffs, Tags, ... immediately
* LXR - Linux Cross Reference
Perl script that generates xref'ed source code in HTML from C++
Not real-time on CVS - rerun by webserver about once a day
* IDEs
* Generating documentation from code
javadoc type tools
by Sun for Java
enriched comments
many different tools - incompatible formats
* ROOT Thtml
Used with ROOT based applications (eg. H1OO?)
Classes to be documented must be included in ROOT
(ClassDef?, ClassImp? Macros)
Need code that sees ALL classes to generate complete documentation
(eg. executable that links everything)
Non C++ Files not documented
Bugs (eg. inline functions don't work correctly)
Unofficial outlook: THtml2
ROOT team choice: rewrite doc tool from scratch, incl. C++ parser etc.
more features: more output formats, code browsing from CINT cmdline, ...
* Doxygen
good results for un-enriched code
too many bells and whistles?
* dot
Graph generation tool from BellLabs?
graphical representation of code structure
simple syntax
used by Doxygen for its graphs
* Noticing Structures:
* What to notice
* Used Coding Standard
Notation for type and scope?
(Rich) comments?
* Design Patterns
example: Singleton
* Framework Facilities
example: messages/error logging
often old/suboptimal solution
* What to skip
* Headers, Initialization
* find point of entry
* How to navigate
* searching
* regexps to reckognize
* grep
* ctags
Part 2: Writing new code
Checking Contributions by others
Writing it yourself
* Checking Contributions
* cvs diff
* Program Syntax Checker
* compile it
* lint
* test suite
* junit, cppunit
junit Covered in CSC
Available in other languages: C++ cppunit
Assert Macros
normally used for test driven development
-> not identical to correctness checking
* Handwritten test suite
Example H1OO? - H1 Fast Validation
Check code based on changes in physics variables
Compare set of observables from identical data
but reconstructed from two different releases
Differences must make sense from physics POV
-> if not, infer indirectly to problems in the code
Very simple implementation, great success for our purposes
* Layout
Coding Standards
* Enforcing Coding standards: Code Beautifiers
* indent
* Jalopy (a java code beautifier)
* More
* Code analyzers PMD (Java)
Testing coverage reports (Clover, JBlanket)
* Summary
* Outlook
Graphical Programming
code browsers
Spinellis D., Code Reading, Addison Wesley 2003
McConnell? s., Code Complete, Microsoft Press, 2nd Ed 2004
... Test Driven Development