Class comments!?
Richard A. O'Keefe
ok at cs.otago.ac.nz
Tue Oct 19 00:06:27 UTC 2004
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.
More information about the Squeak-dev
mailing list
|