Subject: RE: Self-documenting code (ha!)

From: Jamey Hicks <[email-masked]>
Date: Thu, 27 Apr 2000 08:22:29 -0400

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-masked]
++        Please use [email-masked] for           ++
++                        kernel-related discussions.                      ++

---

From: Russell King - ARM Linux Admin <[email-masked]>
Date: Thu, 27 Apr 2000 14:56:45 +0100 (BST)

Jamey Hicks writes:
> Actually, I have trouble with the routines that do not
> 		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

The problem above is a good example of bad comments actually.  Lets say someone
modifies __lookup_processor_type to return a value in r11, and __create_page_tables
to use the value in r11.  They're not really going to update those comments.

This now means that the comments are wrong and confusing.

> I use the documentation at the head of the entry point to remember what the

This is the correct place to comment that detail.

> I think we should be able to maintain single-line inline comments.

RHS comments are more acceptable than inline comments.  However, keeping them
witin the 80 columns is difficult at the best of times.
   _____
  |_____| ------------------------------------------------- ---+---+-
  |   |        Russell King       [email-masked]      --- ---
  | | | |            http://www.arm.linux.org.uk/            /  /  |
  | +-+-+                                                     --- -+-
  /   |               THE developer of ARM Linux              |+| /|\
 /  | | |                                                     ---  |
    +-+-+ -------------------------------------------------  /\\\  |