From owner-freebsd-chat@FreeBSD.ORG Fri Apr 25 15:01:17 2003 Return-Path: Delivered-To: freebsd-chat@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 90ED537B401 for ; Fri, 25 Apr 2003 15:01:17 -0700 (PDT) Received: from heron.mail.pas.earthlink.net (heron.mail.pas.earthlink.net [207.217.120.189]) by mx1.FreeBSD.org (Postfix) with ESMTP id 0970543F85 for ; Fri, 25 Apr 2003 15:01:17 -0700 (PDT) (envelope-from tlambert2@mindspring.com) Received: from pool0134.cvx40-bradley.dialup.earthlink.net ([216.244.42.134] helo=mindspring.com) by heron.mail.pas.earthlink.net with asmtp (SSLv3:RC4-MD5:128) (Exim 3.33 #1) id 199BFl-0007T7-00; Fri, 25 Apr 2003 15:01:10 -0700 Message-ID: <3EA9AFDA.65B1D90E@mindspring.com> Date: Fri, 25 Apr 2003 14:59:54 -0700 From: Terry Lambert X-Mailer: Mozilla 4.79 [en] (Win98; U) X-Accept-Language: en MIME-Version: 1.0 To: Jonathon McKitrick References: <20030422132906.GB64101@dogma.freebsd-uk.eu.org> <444r4qmp6n.fsf@be-well.ilk.org> <20030422172549.GA65023@dogma.freebsd-uk.eu.org> <20030425044935.GG81840@dogma.freebsd-uk.eu.org> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit X-ELNK-Trace: b1a02af9316fbb217a47c185c03b154d40683398e744b8a419d80e7fca1fc7cdc8668274e5a3ca14387f7b89c61deb1d350badd9bab72f9c350badd9bab72f9c cc: freebsd-chat@freebsd.org cc: Dag-Erling Smorgrav Subject: Re: Code layout and debugging time X-BeenThere: freebsd-chat@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Non technical items related to the community List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 25 Apr 2003 22:01:17 -0000 Jonathon McKitrick wrote: > On Wed, Apr 23, 2003 at 11:42:05PM +0200, Dag-Erling Smorgrav wrote: > : Simply put, too much whitespace is just as bad as no whitespace at > : all. Imagine reading a book where every sentence is a separate > : paragraph; paragraph breaks become worthless because they no longer > : serve to group sentences together. > > True, yet a lot of the kernel code and driver code does just that: extensive > commenting, even when it only means one line of code. If you are documenting the hardware in the process of writing the driver, you want extensive comments. This is particularly true if you are doing something clever, the hardware is doing something clever, or the documentation for the hardware is not generally accessible. Personally, I love the comments in most of Bill Paul's network drivers (for example); among other things, vendors have actually read them, and taken them into account for the next generation hardware designs (e.g. RealTek's newer stuff is much better, for the critique of their old stuff). Personally, I think Linux and FreeBSD driver code *should* document the hardware, at least well enough to let someone take a driver written for one of the OSs, and use it to write a driver for some other OS. This means documenting device register bits, rather than poking some magic number into it, and expecting people to blindly follow your lead. -- Terry