The whole paragraph is misworded anyway (before and after), because
it never says one has to use tabs. Just that tabs are 8. Oh wow.
Here's a rewording of everything I am unhappy with, and it goes
a bit further than tabs and spaces.
It may all sound like we are trying to be nitpicky about minuscule
things, but obviously, if there is a way to go against common practice
but still comply to CS, someone will do it in some patch.
Signed-off-by: Jan Engelhardt <jengelh@computergmbh.de>
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index 6caa146..d80fd0f 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -15,23 +15,25 @@ Anyway, here goes:
Chapter 1: Indentation
-Tabs are 8 characters, and thus indentations are also 8 characters.
-There are heretic movements that try to make indentations 4 (or even 2!)
-characters deep, and that is akin to trying to define the value of PI to
-be 3.
+The whole idea behind indentation is to clearly define where a block of
+control starts and ends.
-Rationale: The whole idea behind indentation is to clearly define where
-a block of control starts and ends. Especially when you've been looking
-at your screen for 20 straight hours, you'll find it a lot easier to see
-how the indentation works if you have large indentations.
+There are heretic movements that try to use spaces for indentation. But
+spaces force a specific indentation width on the user. Tabs on the other
+hand provide logical indentation, which means you can set the tab width
+in your editor preferences to any value you like. Especially when you
+have been looking at your screen for 20 straight hours, you will find it
+a lot easier if you can dynamically switch to a higher indent.
-Now, some people will claim that having 8-character indentations makes
+By default, tabs have a width of 8, and most developers use that.
+
+Now, some people will claim that having an 8-wide indentations makes
the code move too far to the right, and makes it hard to read on a
80-character terminal screen. The answer to that is that if you need
more than 3 levels of indentation, you're screwed anyway, and should fix
your program.
-In short, 8-char indents make things easier to read, and have the added
+In short, 8-wide indents make things easier to read, and have the added
benefit of warning you when you're nesting your functions too deep.
Heed that warning.
@@ -77,26 +79,51 @@ Get a decent editor and don't leave whitespace at the end of lines.
Coding style is all about readability and maintainability using commonly
available tools.
-The limit on the length of lines is 80 columns and this is a strongly
-preferred limit.
+The limit on the length of lines is 80 columns, that is when tabs are
+displayed with a size of 8. 80 columns is a strongly preferred limit.
+
+Statements longer than 80 columns should be broken into sensible chunks.
+
+Continuation lines are always shorter than the initial one and are
+(1) indented as much as the initial line, plus (2) alignment spaces.
+Spaces are used so as to not cause odd aligning for users wishing to
+display tabs at sizes other than 8. In the example below, the
+continuation line of the printk call therefore has two tabs of logical
+indent, followed by a number of spaces to align it up.
-Statements longer than 80 columns will be broken into sensible chunks.
-Descendants are always substantially shorter than the parent and are placed
-substantially to the right. The same applies to function headers with a long
-argument list. Long strings are as well broken into shorter strings. The
-only exception to this is where exceeding 80 columns significantly increases
-readability and does not hide information.
+The same applies to function headers with a long argument list. Long
+strings are broken as well into shorter strings. The only exception to
+this is where exceeding 80 columns significantly increases readability
+and does not hide information.
-void fun(int a, int b, int c)
+void fun(int a, int b, int c, struct very_big_structure *ptr,
+ struct lots_of_parameters *ptr2)
{
if (condition)
printk(KERN_WARNING "Warning this is a long printk with "
- "3 parameters a: %u b: %u "
- "c: %u \n", a, b, c);
+ "3 parameters a: %u b: %u c: %u\n"
+ "And our poitners are %p and %p\n",
+ a, b, c);
else
next_statement;
}
+When the function return type, tags and name already takes up a
+significant amount of valuable 80-column space, it is recommended to
+split the long line before the name to reduce the amount of indent
+needed for parameters.
+
+static int __init longmodule_initialize_driver(struct pci_driver *foo,
+ void *some_parameter,
+ void *another_parameter)
+
+into
+
+static int __init
+longmodule_initialize_driver(struct pci_driver *foo, void *some_parameter,
+ void *another_parameter)
+
+
Chapter 3: Placing Braces and Spaces
The other issue that always comes up in C styling is the placement of
@@ -134,7 +161,7 @@ opening brace at the beginning of the next line, thus:
Heretic people all over the world have claimed that this inconsistency
is ... well ... inconsistent, but all right-thinking people know that
(a) K&R are _right_ and (b) K&R are right. Besides, functions are
-special anyway (you can't nest them in C).
+special anyway (you can't nest them in standard C).
Note that the closing brace is empty on a line of its own, _except_ in
the cases where it is followed by a continuation of the same statement,
@@ -178,7 +205,7 @@ if (condition) {
otherwise();
}
- 3.1: Spaces
+ Subchapter 3.1: Spaces
Linux kernel style for use of spaces depends (mostly) on
function-versus-keyword usage. Use a space after (most) keywords. The
@@ -342,6 +369,10 @@ EVER use a typedef unless you can clearly match one of those rules.
In general, a pointer, or a struct that has elements that can reasonably
be directly accessed should _never_ be a typedef.
+Also, using typedefs always requires to #include the header they are
+defined in. If a predeclaration of a struct or union suffices to compile
+the unit without including the header, you even get a speedup.
+
Chapter 6: Functions
--
