Warner Losh writes:
> Good Tone:
> Say Warner, why do you bother turning off the power after
> you suspend a socket. Shouldn't the power routines take care
> of that? Is there something subtle that's going on? Maybe a
> comment is in order?
>
> Bad Tone:
> Please explain the pros and cons for turning the power off
> after suspending a socket. I really want to know. Why did
> they do this? Didn't the coder trust the power routines? The
> least he could have done was include a comment. Was there
> some long discussion that I missed?
>
> See the difference? The first tone is friendly, suggesting that
> something in the code might be unclear. The second seems to imply
> that I'm a moron for not documenting every trivial solution with a 20
> page thesis on why it is good or bad to do.
I am sorry if you interpreted my message as implying that you are a bad
coder or even a moron. I was not thinking either when I wrote it.
However, I do not think your example is a good one in explaining good
versus bad tone. I am sorry if my opinion offends you. You do
excellent work on FreeBSd, as everyone else I have ever encountered who
spends so much time improving the code base also does excellent work.
I am trying to make a point about documentation and its role in helping
to move forward a public-participation project such as FreeBSD. Terry
was trying to make a similar point inhis "Go SOLO 2" posts about the man
pages. Anyone who wants to help out is met by several road blocks.
First, there is a severe problem with understanding the existing code
base. This problem is common in most commercial software projects,
although most companies make some effort at documenting the design, at
least initially. Documenting changes to the design is a real effort. I
am personally a fan of tying the design documentation and code closely
together through design commentary in the code, preferably using
Literate Programming techniques.
Then, there is simply the problem of written communication not being
semantically expressive enough (lack of "tone" to express emotion, and
emoticons do not do a very good job here, ;-)). It is easy to become
intimidated or to inadvertently intimidate others through this medium of
e-mail.
These roadblocks tend to get worse with the barrage of posters who
simply keep shouting "send patches". You cannot patch what you don't
understand and you cannot understand what is not documented. Yes, if,
indeed, the disable/enable pair is time consuming, then it should be
protected by code that tries to make sure it is not called repeatedly.
The simplest solution is a flag or counter to prevent recursive calls.
Also, a timer can prevent calling it in rapid succession. If I can
understand the reasons for the cryptic "XXX" "hack" comment, I can
formulate alternate proposals for potential solutions. I certainly want
to be a constructive member of the community, if at all possible. Right
now I am just trying to learn and point out the road blocks as I
encounter them. If someone chooses to perceive my documentation of my
path to enlightenment as criticism of themselves, that is not my point,
and I am sorry that you take it as a personal critique.
Enough rampling for now.
/Joe
To Unsubscribe: send mail to [EMAIL PROTECTED]
with "unsubscribe freebsd-current" in the body of the message
