Path: utzoo!attcan!uunet!olivea!samsung!cs.utexas.edu!lgc.com!cl
From: cl@lgc.com (Cameron Laird)
Newsgroups: comp.software-eng
Subject: Re: Code inspections
Keywords: inspection, software engineering
Message-ID: <1991Feb1.232201.24240@lgc.com>
Date: 1 Feb 91 23:22:01 GMT
References: <7362@tekchips.LABS.TEK.COM> <1991Jan29.230431.5918@cbnewsm.att.com> <1991Feb1.214750.28536@spool.cs.wisc.edu>
Sender: news@lgc.com
Organization: Landmark Graphics Corp., Houston, Tx
Lines: 40
Nntp-Posting-Host: forest.lgc.com

In article <1991Feb1.214750.28536@spool.cs.wisc.edu> dparter@shorty.cs.wisc.edu (David Parter) writes:
			.
			.
			.
>    6.  If the reviewers do not understand the code, or how it fits
>	into something else, DO NOT RELY ON THE AUTHOR to clarify. 
>	
>	I was the author for a sets of changes to some existing code.
>	The review focused on the parts I changed, not on the program
>	as a whole. I was called upon to give an overview of how it all
>	fit together, and what I had changed. My overview was accepted,
>	the code was approved, and a few days later I found numerous
>	errors that should have been found during the code review (or
>	design review, which is sometimes difficult for modifications
>	to existing code) -- and weren't, because they believed my
>	explanation of how things worked, which turned out to be wrong.
>	Since no members of the review team had an understanding of the 
>	"big picture," at least one of them should have been charged 
>	with doing a more detailed review of the "big picture" in order 
>	to provide the assurances that various assumtions and/or 
>	asertions were valid.
			.
			.
			.
This is an IMPORTANT rule, and one which applies far, far beyond
inspections.  One of the best things we can do for each other is
to cultivate the attitude that authors don't get to explain them-
selves (well, they do, but only on special occasions).  Authors
*must* push themselves to write so that they can be understood;
if readers/reviewers/inspectors don't understand, that is (in gen-
eral) a sign that the author needs to rewrite (most often:
comment more clearly) what he or she has written.  One of the
nice things about this rule is that it's easy to teach:  each time
an author starts, "Well, what I'm trying to do there is ...", his
or her colleagues need immediately to remind, "Then *say* ..., IN
THE SOURCE."
--

Cameron Laird		USA 713-579-4613
cl@lgc.com		USA 713-996-8546