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