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
