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

From: Jamey Hicks <[email-masked]>
Date: Thu, 27 Apr 2000 12:59:50 -0400

Russell,

> Jamey Hicks writes:
> > 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
> 
> 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.

I think there are enough eyeballs looking at this code and submitting
patches that we ought to be able to maintain a few partial lines of
comments.

I should hope anyone who modifies what __lookup_processor_type does looks at
where it is called and updates the caller as well.

I think a few more comments would help increase the size of the linux hacker
community.

-Jamey

unsubscribe: body of `unsubscribe linux-arm' to [email-masked]
++        Please use [email-masked] for           ++
++                        kernel-related discussions.                      ++

---

From: "Steven J. Hill" <[email-masked]>
Date: Thu, 27 Apr 2000 13:54:40 -0500

Jamey Hicks wrote:
> I should hope anyone who modifies what __lookup_processor_type does looks
> at where it is called and updates the caller as well.
> 
> I think a few more comments would help increase the size of the linux
> hacker community.
> 
Well, if Russell accepts my patches, you will see new additional comments
in 'head-armv.S'. Let's just approach this [documentation] a piece at a time
and it will eventually get better. 

-Steve

-- 
 Steven J. Hill - Embedded SW Engineer
 Public Key: 'finger [email-masked]'
 FPR1: E124 6E1C AF8E 7802 A815
 FPR2: 7D72 829C 3386 4C4A E17D