Date: Sun, 12 Aug 2001 20:40:53 -0700 From: Joe Kelsey <joe@zircon.seattle.wa.us> To: current@FreeBSD.ORG Subject: "Good" Tone vs. "Bad" tone Message-ID: <15223.19525.421003.634900@zircon.zircon.seattle.wa.us> In-Reply-To: <200108130211.f7D2BSW04119@harmony.village.org> References: <15223.10812.286362.192448@zircon.zircon.seattle.wa.us> <15222.50892.75406.972475@zircon.zircon.seattle.wa.us> <200108120813.RAA26578@zodiac.mech.utsunomiya-u.ac.jp> <200108130044.f7D0igW03766@harmony.village.org> <200108130211.f7D2BSW04119@harmony.village.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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 majordomo@FreeBSD.org with "unsubscribe freebsd-current" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?15223.19525.421003.634900>