> >>        * "anyone who needs to know can look at the code to figure it
> >>          out."
> >
> >For me, part of 'quality code' has always been sufficient commenting _and_
> >documenting. But I am under the impression that it is more important that
> >NetBSD sources be tabbed according to KNF than that they are documented...
> 
> Functionality seems to be the more important concern here. People are
> happy enough just to get stuff working. 

Looks like it. But all too often the result is code that can neither be
maintained by the writer nor by anyone else. I have quite a history of
putting some sense into other peoples' code, and although the job has
become something of a favourite I still feel rather strong about the
issue.

> I generally like to comment as I go which usually results in too many
> comments and KNF seems to frown on this. Other folks like the "go back and
> comment later" method. Unfortunately, "later" either never occurs or they
> forgot exactly what the code did :)

Clean up your comments as you clean up your code, try to read them with
'a beginner's mind' and check if they still make sense. Cluster comments
and code (/* the next block does... */), and if you find that a complex
issue needs a lengthy explanation, pull it out into an external doc. For
example, I certainly won't drop the explanation of how the IWM works
into the assembler source file: It would make both the code and the docs
unreadable.

Layer your docs as you would layer your software, and all's well...
 
[...]
 
> What kind of software engineering nonsense is this? We're making an OS
> here, not an ADA program for the Department of Defense. I suppose you'd
> like a Z specification as well? Go program in Prolog! ;-) ;-) ;-) ;-)

 :)

Well, afaik NetBSD is a group effort. When you get that real great job
that unfortunately leaves not much time for anything else, some other
guy has to be able to pick your grf drivers and run from there...
(BTW: What is a Z spec?)

> It's easy when you're adding a major hunk of functionality to write up a
> document but what happens when you just patch this and that temporarily or
> add a few lines of code? Most people just don't feel the need to bother.

Comment your changes?

>  Michael Zucca - mrz5149@rit.cs.rit.edu - http://www.rit.edu/~mrz5149/


        hauke

-- 
"It's never straight up and down"  (DEVO)