> It would have taken the original author maybe 10 minutes 
> to explain what he was up to in those 20 lines.  
> It would have saved me a week. 


How about "audio comments" voice recorded, with a EventRecorderMorph
like walkthrough?

Do we verbally explain code (say, in a conference presentation) by
reciting the code outloud? 
If so, we really should save our breath when explaining the 10 lines or
so that make up Seaside.  ;)


Cheers, 
Darius 




 

-----Original Message-----
From: squeak-dev-bounces at lists.squeakfoundation.org
[mailto:squeak-dev-bounces at lists.squeakfoundation.org] On Behalf Of
Richard A. O'Keefe
Sent: Monday, October 18, 2004 5:06 PM
To: squeak-dev at lists.squeakfoundation.org
Subject: Re: Class comments!?

Michael Latta <lattam at mac.com> wrote:
	This was driven home recently when the author / maintainer of a
piece 
	of our product was unavailable and I was asked to step in and
make an 
	enhancement.  Without comments (or documentation) to get started
I was 
	unable to be effective on short notice, and the task was put on
hold 
	waiting for the original developer to have time.  But, in those
cases 
	where the original developer is never going to have time (key
person or 
	just gone), the lack of contextual documentation is a huge risk
to any 
	organization.
	
A company I once worked at had a single product.  One day we found that
there was a bug in an absoutely critical module.  If that module didn't
work, we couldn't trust anything to work.

The original author had left the company.

There were two comments in a couple of thousand lines.

One was a copyright notice.

The other commented out a few lines of code with the note "This doesn't
work."
(That's not where the bug was.)

I spent a week working through the code, understanding it one layer at a
time, writing comments and test code.  (The function of the test code
was
to test that my understanding was correct, which it often wasn't.)

Once I understood what the code was *supposed* to do, I was not only
able
to repair the bug, but to make the code cleaner and thereby make it 20%
faster.
However, I wasn't _really_ able to repair the bug, but only to write a
wrapper
around the part where the bug was that detected whether the bug was
about to
occur and if so "deoptimise" the input so that the bug didn't bite.
There
was a crucial algorithm, only about 20 lines of code, and I never did
figure
it out.

It would have taken the original author maybe 10 minutes to explain what
he
was up to in those 20 lines.  It would have saved me a week.





***********************************************************************************
This transmission contains information which may be legally privileged, proprietary in nature, or otherwise protected by law from disclosure, and is intended only for the use of the addressee(s) named above. If you are not the addressee, or the person responsible for delivering this to the addressee(s), you are hereby notified that reading, copying, or distributing this transmission is prohibited. If you have received this transmission in error, please telephone us immediately at 818-407-1400 and mail the transmission back to us at the above address.

This footnote also confirms that this email message has been swept by
MIMEsweeper for the presence of computer viruses.
***********************************************************************************