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 ?
 
Introduction
 
   
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
 
   
Outline
 
   
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)
   
Details
 
   
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
 
       
* XREF
       
* IDEs
 
* Generating documentation from code
 
   
javadoc type tools
   
javadoc:
       
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
 
   
popular
   
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?
         
Layout?
         
(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
 
Bibliography
 
 
Spinellis D., Code Reading, Addison Wesley 2003
 
McConnell? s., Code Complete, Microsoft Press, 2nd Ed 2004
 
... Test Driven Development