Riccardo

"This means you can spend a lot of time arguing with the compiler but once your program compiles it has a high likelihood of being correct."

If you want the same experience, but in an imperative context, switch to Ada. I used it for quite some time now and I can say that if you exploit the tools the language gives you, you get a code well armored against bugs (current and future).

I never used Haskell, but I know some programmers who like and use both Ada and Haskell.

Let me add my 2.0e-2 cents.
Speaking on a very, very general basis (your mileage may vary) I find that what I miss more in some OS projects is a very high-level view of the structure of the software. Often you find in the /doc directory a group of automatically generated *.html files with the inheritance diagrams of the classes and prototypes of the functions. This is <em>too detailed</em> documentation. If you are an experienced developer, it can be useful to have something that reminds you that Audio_Bugaboo inherits from Multimedia_Bugaboo that in turns inherit from Abstract_Bugaboo, but for a newbie who does not know _what_ a Bugaboo is and what it should do, it can be more useful a rough block diagram that shows where a Bugaboo enters in the picture.

Another place where I would like to see some documentation (and where I usually put it) is in the *.h files (well, actually in *.ads files. I use Ada...). From my point of view, a developer is a _user_ of the small module that your .c file implements and the best place where to put the instructions for using the module is the .h file. However, often what you find inside, say, multibugaboo.h is a one-line comment similar to

<code>
/* multibugaboo.h: Multibugaboo implementation */
</code>

Duh... Really?!? That is a surprise...
What in the $place is a Multibugaboo?!? What is its duty?!!? What kind of function/procedure/data structures this module provides?!? By the way, it is not necessary a detailed description of the internal details of a multibugaboo (if you really need, put them in the .c file), just a very high-level description would suffice, so that if I am searching for the code that is formatting the packets and send them over the network, I know if I am in the right file or not.

[[ Sorry for the rant... Imagine lots of smiles next to it :-) :-) :-) I am smiling while I write, but the electronic mean do not carry this kind of side-information. ]]

So, bottom line, high-level documentation is what a newbie often needs. Paradoxically, documenting the finest details is not maybe so important, they can be deduced from a nicely written code. Moreover, it could give rise to problems if the implementation details change, but the comments do not.

Let me conclude by telling you my personal approach to this problem. In order to practice what I preach, I found it useful to keep a wiki (edited only by myself) to be used as a notepad for ideas. The wiki gives you an easy way to keep your notes well-ordered and it is sufficiently fast to not mess with the flow of your ideas. At the end, the wiki, suitably refined, should be a good basis for the high-level overview. Also, scanned hand-drawn pictures make good place-holder for diagrams & stuff to be produced later with some drawing software. Of course, your mileage may vary...