Code layout and debugging time

[Terry Lambert]

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