[PATCH] coding style addendum

[PATCH] coding style addendum

[Luben Tuikov]

Someone may find this helpful and descriptive of how kernel code
should be developed.

--- linux-2.5.64/Documentation/CodingStyle.orig	2003-03-10 11:23:46.000000000 -0500
+++ linux-2.5.64/Documentation/CodingStyle	2003-03-10 11:37:18.000000000 -0500
@@ -1,3 +1,4 @@
+Updated: Mon Mar 10 16:34:35 UTC 2003

  		Linux kernel coding style

@@ -264,3 +265,26 @@

  Remember: if another thread can find your data structure, and you don't
  have a reference count on it, you almost certainly have a bug.
+
+
+		Chapter 9: Organization
+
+Writing efficient code is important in both complexity and
+implementation.  In other words your code organization should NOT be
+too complex to understand.  Complexity directly depends on the choice
+of data representation and code organization.  To help you stay in
+line, here are a few guidelines to follow:
+
+      Modularize.
+      Use subroutines.
+      Each subroutine/module should do one thing well.
+      Make sure every module/subroutine hides something.
+      Localize input and output in subroutines.
+
+And the most important:
+
+    Choose the data representation that makes the program simple.
+
+
+			      ----------
+

Re: [PATCH] coding style addendum

[Richard B. Johnson]

On Mon, 10 Mar 2003, Luben Tuikov wrote:

> Someone may find this helpful and descriptive of how kernel code
> should be developed.
[SNIPPED...]

> +      Make sure every module/subroutine hides something.

This is not correct. Well known example:

#include <math.h>

double hypot(double x, double y) {
    return sqrt((x * x) + (y * y));
}

This subroutine hides nothing. It receives input parameters
and returns the result of its operations. Such a subroutine
is properly implemented and should not be be forced to hide
anything.

The input parameters are copies, owned by the called function.
They can be manipulated like local data and must not be required
to be copied into "local data". The return value is also not
locally stored and therefore not hidden. Your rule would require
the replication of three floating-point variables NotGood(tm).

Cheers,
Dick Johnson
Penguin : Linux version 2.4.20 on an i686 machine (797.90 BogoMips).
Why is the government concerned about the lunatic fringe? Think about it.

Re: [PATCH] coding style addendum

[Luben Tuikov]

Richard B. Johnson wrote:
> On Mon, 10 Mar 2003, Luben Tuikov wrote:
> 
> 
>>Someone may find this helpful and descriptive of how kernel code
>>should be developed.
> 
> [SNIPPED...]
> 
> 
>>+      Make sure every module/subroutine hides something.
> 
> 
> This is not correct. Well known example:
> 
> #include <math.h>
> 
> double hypot(double x, double y) {
>     return sqrt((x * x) + (y * y));
> }
> 
> This subroutine hides nothing. It receives input parameters

It does hide something.  It hides *the implementation* of
the function hypot().

In effect, elsewhere in your code you could have the explicit
	... = sqrt((x * x) + (y * y));
or,
	... = hypot(x, y);

It's just eliminating (code) redundancy and duplication.

I.e. this addendum was meant on a more abstract/logical ground, thus the
name of the chapter.

[cut]
> locally stored and therefore not hidden. Your rule would require
> the replication of three floating-point variables NotGood(tm).

This isn't really my rule.  I didn't invent or came up with anything
new here.

Documentation/CodingStyle is remarkably similar to most of what
you'd find in [1], and those rules are more or less from that
same book.

Actually, the whole point of my posting the patch is the last rule,
since well thought out data representation makes or breaks the code.

References:
[1] ``The Elements of Programming Style'' by Kernighan
and Plauger, 2nd ed, 1988, McGraw-Hill.

-- 
Luben

Re: [PATCH] coding style addendum

[Tommy Reynolds]

Uttered Luben Tuikov <luben@splentec.com>, spoke thus:

>  References:
>  [1] ``The Elements of Programming Style'' by Kernighan
>  and Plauger, 2nd ed, 1988, McGraw-Hill.

Keep in  mind the date here.   Prior to this time,  subroutines were the
packaging  technique  of choice  to  promote  "software reuse":  i.  e.,
reference the _same_  code in various places throughout  a program.  K&P
were espousing a  fundamental shift in thinking by  using subroutines as
functional  abstractions.  Using  your  argument that  the example  code
hides an "implementation", it's difficult  to conceive of a code example
that hids neither its data nor its implementation.


I'd suggest an alternate tack:

        "When you are deep in the programming 'zone' and code is flowing
        from  your fingertips  and you  are  amazed at  the insight  and
        understanding evidenced by your code:

        STAND UP!  MOVE AWAY FROM THE KEYBOARD!  GO HOME!

        Look at the code again tomorrow and see if it makes any sense to
        you then."

Re: [PATCH] coding style addendum

[Luben Tuikov]

Tommy Reynolds wrote:
>> References:
>> [1] ``The Elements of Programming Style'' by Kernighan
>> and Plauger, 2nd ed, 1988, McGraw-Hill.
> 
> 
> Keep in  mind the date here.   Prior to this time,  subroutines were the

Yes, I'm aware of the date.  AFAIR, 1 ed. is circa 1974, so in 14 years
I'd say the principles were still effective.

``Prior to this time'' you probably meant prior to 1974.

[cut]
> functional  abstractions.  Using  your  argument that  the example  code
> hides an "implementation", it's difficult  to conceive of a code example
> that hids neither its data nor its implementation.

So why should you change a definition to allow for a specific case?
Isn't a function de facto an implementation detail and thus encapsulating
the actual implementation (i.e. it's workings).
Anyway this is not important and is just formalisms.

My whole point was to put down in text file, the already practiced rule
of thinking out data representations, since this has direct effect on
the complexity of the code (i.e. the choice of data represenation).

I'm sure you know which example I'm thinking of.

-- 
Luben