coding style addendum

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

@@ -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.
+
+
+			      ----------
+

[SNIPPED...]

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.

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]

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

Uttered Luben Tuikov <[email protected]>, spoke thus:

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."

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]

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