I don't really agree with the argument that we shouldn't document code
because entropy happens. On the other hand, I don't think the documentation
should be verbose because it gets in the way of the code. Good code should
be self-documenting without much in the way of comments: a short description
at the entry point, descriptive procedure and variable names, and then
comments highlighting anything that might be difficult to understand.
> > The same arguement applies here - I can't keep the contents of all
> > the registers straight in my mind as they are carried from one block
> > to another.
>
> You don't have to. Any that are transferred between the
> various "functions"
> is documented in the comments before the function, thus:
>
> /*
> * Read processor ID register (CP#15, CR0), and determine
> * processor type.
> *
> * Returns:
> * r5, r6, r7 corrupted
> * r8 = page table flags
> * r9 = processor ID
> * r10 = pointer to processor structure
> */
I think the comments at the beginning of the routines in head-armv.S are a
great help, but I still have trouble keeping the registers straight from one
reading to the next. Actually, I have trouble with the routines that do not
follow the standard calling convention, such as _lookup_processor_type. I
keep recommenting the code with those exceptions, e.g.,
bl __lookup_processor_type @ returns values in
r8, r9, r10
...
bl __lookup_architecture_type @ returns values in
r5, r6, r7
...
bl __create_page_tables @ uses r5, r6, r8,
r8
I use the documentation at the head of the entry point to remember what the
values were.
I submitted this as a patch once, but it seems to have been misplaced.
I think we should be able to maintain single-line inline comments. I think
it's worth doing in assembly language, where we do not have the advantage of
variable names as an aid to understanding the code. A little work here
might help increase the size of the ARM Linux community.
-Jamey Hicks
unsubscribe: body of `unsubscribe linux-arm' to [EMAIL PROTECTED]
++ Please use [EMAIL PROTECTED] for ++
++ kernel-related discussions. ++
