On 2005.03.06, Andrew Piskorski <[EMAIL PROTECTED]> wrote:
> So, as AOLserver developers maintain and renovate any code, I highly
> encourage you not only to fix distracting formatting issues, but to
> also add any additional explanatory comments which you believe useful,
> especially of the "why" type.
I'd rather folks not litter the code and instead send an email to the
AOLSERVER mailing list referring to the file name(s) and CVS revision
numbers and line numbers that they're questioning.
9.99 times out of 10 (feel free to round up) if the code isn't
communicating its intent, the answer is NOT to comment the code, but
to refactor it so it communicates its intent clearly. If there's a
block of code that needs to be refactored out and its purpose named with
a function, then apply the Extract Method refactoring, especially if it
removes duplication. Of course, in a multi-threaded app. we have to
deal with locks and lock contention, and minimizing the time spent in a
hot section is important -- so, extracting methods may not be attractive
(unless we start using compiler hints to inline methods, etc. but lets
not go there yet). In those cases, perhaps a comment is appropriate,
but I'd still rather at least attempt to refactor the code itself to
make it communicate better before "giving in" and commenting it.
Comment graffiti ("I WUZ HERE, WHUT DUZ THIS C0D3 [EMAIL PROTECTED]") is
just that. Please, don't do it. :-) Use the mailing list to ask
questions *OR* the online chat.
...
On the other hand, I do think a set of very high-level design documents
that outline the overall strategies implemented in AOLserver would be
useful. I'm thinking at the level that would be suitable as bullet
points on a PowerPoint deck, like: "AOLserver 4.1 employs a single
driver thread to accept TCP connections then dispatches requests to
connection threads for request processing." That's as detailed as I'd
go -- this way, as the actual implementation changes, it doesn't
immediately obsolete large chunks of the design doc.
-- Dossy
--
Dossy Shiobara mail: [EMAIL PROTECTED]
Panoptic Computer Network web: http://www.panoptic.com/
"He realized the fastest way to change is to laugh at your own
folly -- then you can let go and quickly move on." (p. 70)
--
AOLserver - http://www.aolserver.com/
To Remove yourself from this list, simply send an email to <[EMAIL PROTECTED]>
with the
body of "SIGNOFF AOLSERVER" in the email message. You can leave the Subject:
field of your email blank.
