Date: Fri, 25 Apr 2003 14:59:54 -0700 From: Terry Lambert <tlambert2@mindspring.com> To: Jonathon McKitrick <jcm@FreeBSD-uk.eu.org> Cc: Dag-Erling Smorgrav <des@ofug.org> Subject: Re: Code layout and debugging time Message-ID: <3EA9AFDA.65B1D90E@mindspring.com> 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>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?3EA9AFDA.65B1D90E>