Hurd package?
Mail?
HUH?
dave
>
> Greetings, Hurders of the GNUMach!
>
> Today, my Hurd package came in the mail!
>
> A great thanks to Neal for that! You saved me a fortune that would otherwise have
>gone to greedy, dishonest monopoly-abusers called
> Belgacom ... they still own the phone-lines ... but the day will come ... we will
>overcome, one day!
>
> Like I said, I would like to produce documentation as I go, and I have a suggestion
>that I hope to get some support for:
>
> I would like to begin every source file with a description of the module implemented
>by the source file.
> This should strengthen cohesion and maybe even weaken coupling in the modules:
> If you have to describe each source file, you will automatically think about whether
>the different functions in the source file
> ('module') logically belong together - you may get stronger cohesion for free just
>by writing the description, and immediately start
> thinking about whether or not a specific function might 'belong to another module'.
>This will also keep us thinking about interfaces
> between modules and functions, and such thoughts can be good for the coupling
>between modules, since you are also thinking about
> what the functions need to know about one another.
> But this is not the reason why I want to do it this way: As a newbie, I want to get
>some idea of 'where I am' in the source tree,
> when I read about a function, I want to see the 'big picture', knowing what module
>the function is in, and where that module is in
> the system. I hope to get some support for this.
> Before each function I would then give a description of the function.
> I am strongly influenced by the hacker idea that code is self-explanatory, I prefer
>to have the 'comments' on top, explaining the
> function in broader terms, so that the source code is just a way fo say: Look, this
>is how I chose to do it.
> Module organization, however, is far from self-explanatory. Except for some
>brilliantly laid-out source trees, like Linux
> (drivers/net/hamradio/soundmodem) module organisation must be documented somewhere
>if we hope to make sense of it - which brings me
> to the structuring of the function/module descriptions.
> I believe that if every description starts off with an explanation of WHY the module
>of function is created, it will serve several
> purposes.
> When coding, we will be invited to think about the function's purpose, when we are
>really only concerned with it's implementation.
> This will keep us from adding unnecessary 'chrome' that might be fun to have, but
>that really does not add anything to the system's
> functionality, and more important, might confuse people new to the system (like me,
>Atle, but others will come, I hope :-).
> I would like the heading to say: "PROBLEM - a brief statement of the problem that
>this function solves."
> But, helping the implementor is not my first priority, my first priority is helping
>ME, the newbie.
> When looking at a function, I will want to know what the purpose of that function
>is, that will greatly help me understand it's
> implementation, in fact, I will probably find that I know how it is implemented
>before starting to actually read it.
> And most of all: If I start in one end of the Hurd, adding these things as I go, I
>will not be able to avoid learning the Hurd.
> Hopefully, I will have acted like a snow-plow, plowing away 'snow' of ignorance, so
>that the ones that come after me, can follow at
> full speed.
> Hopefully, it will be like having <<Prev ^^Up vvDown Next>> pointers in the
>documentation:
>
> /***********************
> PROBLEM
> Accessing some arrays is too slow.
> A data item is only entered once,
> but often read inside a loop.
> A real processor pig.
> SOLUTION
> Using binary search, getting the avearge
> number of accesses down from 15986 to 15
> this is a formidable speedup.
> array_search(void *pArray, void* keydata, int (*cmpf)())
> {
> int h, l; /* Higher and lower boundary of srchspc */
> /* Oh yes, add comments as before ! */
> }
>
> But I don't want to mess up anyone's work, so at least in the beginning, I will ask
>before changing anything, even if I think it is
> a good idea.
>
> What I am looking for here, is to see if people in general would like this, if you
>think it is useful, and if not, please tell me,
> and please also tell me why you think I am wrong, because I can't see anything wrong
>with this, in fact I am even puzzled why it is
> not done like this everywhere ....
> Thanks, Atle
>
>
Avoid Quiet and Placid persons unless you are in Need of Sleep.
-- National Lampoon, "Deteriorada"
