Darren New <dne### [at] sanrrcom> wrote:
> *I* would pass it!  :-)   Seriously, it boggles me that there are people
> smart enough to do a week's worth of coding without ever having to write
> anything down.

Well, when not coding for cash, I typically just happily hack away in some kind
of "autopilot" mode, interspersing a few comments (typically to other people's
code I didn't fully understand at first glance ;)), until I run into something
seriously complicated - usually involving a non-trivial interface between two
modules or such, with a chance of generating deadlocks, race conditions,
unhandled errors, and/or poorly defined responsibilities.

At that point, I first take a pee, then a *deep* breath, then hack up about a
page's worth of comments into the source code file (or a separate file
occasionally) about how I want the things to interface, find that there are
loopholes, replace half of the smash with a better approach or more precise
description, and iterate over and over again until I have a clear, airtight
contract for the interface to stick to. Which may take a few hours, or
occasionally days.

*Then* I continue coding.

> It's not that hard to do. You just spend 20 minutes writing down what you're
> planning to do as you plan it. A one-page "this is how the code is laid out"
> document does wonders.

I'm not really good at 20-minutes-docs: As soon as I start documenting, I just
can't keep myself from drilling down into all the details...

> What would you rather interface to: A protocol specified by an RFC, or a
> protocol specified by a big chunk of C code?

Why, the RFC of course.

Note however that the task of interfacing to a protocol is somewhat different
from doing maintenance work on an existing piece of software.

Post a reply to this message