PATCH, RFC: 2.6 Documentation/Codingstyle
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
"MF" == Michael Frank <[email protected]> writes:
MF> Comments and suggestions are appreciated.
Aside from the spelling & wording problems already commented on by others (all of which I happen to agree),...
----------------------------------------------------------------
MF> This is a short document describing the preferred coding style for the MF> linux kernel. Coding style is very personal, and I won't _force_ my MF> views on anybody,... MF> ... Anyway, here goes:
The above introductory paragraph needs to be rewritten if you plan to start using CodingStyle document to record the developer community consensus. The words "I" and "my" used here refer to Linus and Linus only; IIRC, the coding style document originates from an old posting by him to the l-k mailing list, and the intent was to express view of Linus so that he does not have to get involved in coding style flamewar on l-k list every time.
----------------------------------------------------------------
MF> +Note that perhaps the most terrible way to write code is to put multiple MF> +statements onto a single line:
MF> + if (condition) do_this;
I do not think this particular one agrees with community consensus yet. If "do_this" is short and sweet, I would not be surprised if Linus said it is perfectly fine.
If the community indeed wants to ban a short single statement as the body of an "if" statement, I would rather write the bad example as this:
if (condition) never_do_this;
----------------------------------------------------------------
MF> +Lagging spaces are deprecated.
You probably meant "trailing spaces". In addition to that you may also want to say something about <SP>s before <TAB>.
----------------------------------------------------------------
MF> +void fun(int a, int b, int c)
MF> +{
MF> + if (condition)
MF> + printk(KERN_WARNING "Warning this is a long printk with "
MF> + "3 parameters a: %u b: %u "
MF> + "c: %u \n", a, b, c);
MF> + else
MF> + next_statement;
MF> +}
This example violates indent by tab rule (notice spaces before "else").
----------------------------------------------------------------
MF> +Complex expressions are easier to understand and maintain when extra MF> +parenthesis are used. Here is an extreme example
MF> +
MF> +x = (((a + (b * c)) & d) | e) // would work also without any parenthesis
I believe this goes against community consensus not to overuse parentheses. Linus and others are also against "if ((a = b)) { ... }" (place extra parens around assignment expression used as boolean), which is what GCC suggests (and which indeed is a stupid suggestion).
----------------------------------------------------------------
MF> +Periods terminating kernel messages are deprecated MF> +Usage of the apostrophe <'> in kernel messages is deprecated
I do not think encouraging bad spelling like above has reached community consensus. Personally I do not like those sloppy grammar ("donts" and missing period at the end of the sentence).
Encouraging people to be consistent is a good thing, but I do not want to encourage people to be consistently sloppy.
Quoted 6 lines · Junio C Hamano
MF> +Periods terminating kernel messages are deprecated MF> +Usage of the apostrophe <'> in kernel messages is deprecated
I do not think encouraging bad spelling like above has reached community consensus. Personally I do not like those sloppy grammar ("donts" and missing period at the end of the sentence).
About dots. Let's look how it would look like with those dots added everywhere, and then with dots removed.
klogd 1.4.1, log source = /proc/kmsg started.
Linux version 2.4.22-rc2_QoS (root@vda) (gcc version 3.2) #1 Tue Nov 18 15:55:00 GMT-2 2003.
BIOS-provided physical RAM map:
BIOS-e820: 0000000000000000 - 000000000009e000 (usable).
BIOS-e820: 000000000009e000 - 00000000000a0000 (reserved).
BIOS-e820: 00000000000c0000 - 00000000000cc000 (reserved).
BIOS-e820: 00000000000dc000 - 0000000000100000 (reserved).
BIOS-e820: 0000000000100000 - 0000000007cf0000 (usable).
BIOS-e820: 0000000007cf0000 - 0000000007cff000 (ACPI data).
BIOS-e820: 0000000007cff000 - 0000000007d00000 (ACPI NVS).
BIOS-e820: 0000000007d00000 - 0000000007e80000 (usable).
BIOS-e820: 0000000007e80000 - 0000000008000000 (reserved).
BIOS-e820: 00000000ff800000 - 00000000ffc00000 (reserved).
BIOS-e820: 00000000fff00000 - 0000000100000000 (reserved).
126MB LOWMEM available.
On node 0 totalpages: 32384.
zone(0): 4096 pages.
zone(1): 28288 pages.
zone(2): 0 pages.
Kernel command line: root=/dev/nfs nfsroot=172.16.42.75:/.rootfs/.std,hard,intr ip=:172.16.42.75:::(none):eth0:dhcp devfs=mount. Initializing CPU#0.
Detected 1196.031 MHz processor.
Console: colour VGA+ 80x30.
Calibrating delay loop... 2385.51 BogoMIPS.
Memory: 123856k/129536k available (2268k kernel code, 5224k reserved, 694k data, 564k init, 0k highmem). Dentry cache hash table entries: 16384 (order: 5, 131072 bytes).
Inode cache hash table entries: 8192 (order: 4, 65536 bytes).
Mount cache hash table entries: 512 (order: 0, 4096 bytes).
Buffer cache hash table entries: 4096 (order: 2, 16384 bytes).
Page-cache hash table entries: 32768 (order: 5, 131072 bytes).
CPU: L1 I cache: 16K, L1 D cache: 16K.
CPU: L2 cache: 256K.
Intel machine check architecture supported.
Intel machine check reporting enabled on CPU#0.
CPU: After generic, caps: 0383fbff 00000000 00000000 00000000. CPU: Common caps: 0383fbff 00000000 00000000 00000000. CPU: Intel(R) Celeron(TM) CPU 1200MHz stepping 01.
Enabling fast FPU save and restore... done. Enabling unmasked SIMD FPU exception support... done. Checking 'hlt' instruction... OK.
Checking for popad bug... OK.
POSIX conformance testing by UNIFIX.
mtrr: v1.40 (20010327) Richard Gooch ([email protected]).
mtrr: detected mtrr type: Intel.
PCI: PCI BIOS revision 2.10 entry at 0xfd9b8, last bus=1.
PCI: Using configuration type 1.
PCI: Probing PCI hardware.
PCI: Probing PCI hardware (bus 00).
Kinda ugly, isn't it?
klogd 1.4.1, log source = /proc/kmsg started
Linux version 2.4.22-rc2_QoS (root@vda) (gcc version 3.2) #1 Tue Nov 18 15:55:00 GMT-2 2003
BIOS-provided physical RAM map:
BIOS-e820: 0000000000000000 - 000000000009e000 (usable)
BIOS-e820: 000000000009e000 - 00000000000a0000 (reserved)
BIOS-e820: 00000000000c0000 - 00000000000cc000 (reserved)
BIOS-e820: 00000000000dc000 - 0000000000100000 (reserved)
BIOS-e820: 0000000000100000 - 0000000007cf0000 (usable)
BIOS-e820: 0000000007cf0000 - 0000000007cff000 (ACPI data)
BIOS-e820: 0000000007cff000 - 0000000007d00000 (ACPI NVS)
BIOS-e820: 0000000007d00000 - 0000000007e80000 (usable)
BIOS-e820: 0000000007e80000 - 0000000008000000 (reserved)
BIOS-e820: 00000000ff800000 - 00000000ffc00000 (reserved)
BIOS-e820: 00000000fff00000 - 0000000100000000 (reserved)
126MB LOWMEM available
On node 0 totalpages: 32384
zone(0): 4096 pages
zone(1): 28288 pages
zone(2): 0 pages
Kernel command line: root=/dev/nfs nfsroot=172.16.42.75:/.rootfs/.std,hard,intr ip=:172.16.42.75:::(none):eth0:dhcp devfs=mount Initializing CPU#0
Detected 1196.031 MHz processor
Console: colour VGA+ 80x30
Calibrating delay loop... 2385.51 BogoMIPS
Memory: 123856k/129536k available (2268k kernel code, 5224k reserved, 694k data, 564k init, 0k highmem) Dentry cache hash table entries: 16384 (order: 5, 131072 bytes)
Inode cache hash table entries: 8192 (order: 4, 65536 bytes)
Mount cache hash table entries: 512 (order: 0, 4096 bytes)
Buffer cache hash table entries: 4096 (order: 2, 16384 bytes)
Page-cache hash table entries: 32768 (order: 5, 131072 bytes)
CPU: L1 I cache: 16K, L1 D cache: 16K
CPU: L2 cache: 256K
Intel machine check architecture supported
Intel machine check reporting enabled on CPU#0
CPU: After generic, caps: 0383fbff 00000000 00000000 00000000 CPU: Common caps: 0383fbff 00000000 00000000 00000000 CPU: Intel(R) Celeron(TM) CPU 1200MHz stepping 01
Enabling fast FPU save and restore... done Enabling unmasked SIMD FPU exception support... done Checking 'hlt' instruction... OK
Checking for popad bug... OK
POSIX conformance testing by UNIFIX
mtrr: v1.40 (20010327) Richard Gooch ([email protected])
mtrr: detected mtrr type: Intel
PCI: PCI BIOS revision 2.10 entry at 0xfd9b8, last bus=1
PCI: Using configuration type 1
PCI: Probing PCI hardware
PCI: Probing PCI hardware (bus 00)
Personally I like this better
--
vda
You haven't made your point with this post.
Dots are meant to end sentences not lines.
If a line is not a sentence there's no point in adding a period. Period. However if a message is basically a sentence then like any sentence it should end with a period. There's no philosophy to this.
The majority of kernel messages aren't sentences and thus are dot-free. Some however are, and these usually look better with the ending periods. However, whether these ending periods are necessary depends mainly on the length of the sentence, on whether they end with numerals or acronyms and a matter of personal taste.
Quoted 9 lines · vda
Quoted 6 lines · Junio C Hamano
MF> +Periods terminating kernel messages are deprecated MF> +Usage of the apostrophe <'> in kernel messages is deprecated
I do not think encouraging bad spelling like above has reached community consensus. Personally I do not like those sloppy grammar ("donts" and missing period at the end of the sentence).
Quoted 5 lines
126MB LOWMEM available
Detected 1196.031 MHz processor Intel machine check architecture supported POSIX conformance testing by UNIFIX
PCI: Probing PCI hardware
In your post only the above could be considered sentences and even then most are really too short, or end with numerals or acronyms which make dots look stupid. Personally I'd think the "Intel machine check architecture supported." message looks better with a period and I'd leave all the rest alone. Nevertheless, all 5 of the above could possibly end with periods, the rest never.
De gusto non est disputandum - cheers,
MaZe.
Quoted 6 lines · Maciej Zenczykowski
Quoted 5 lines
126MB LOWMEM available
Detected 1196.031 MHz processor Intel machine check architecture supported POSIX conformance testing by UNIFIX
PCI: Probing PCI hardware
Quoted 6 lines
In your post only the above could be considered sentences and even then most are really too short, or end with numerals or acronyms which make dots look stupid. Personally I'd think the "Intel machine check architecture supported." message looks better with a period and I'd leave all the rest alone. Nevertheless, all 5 of the above could possibly end with periods, the rest never.
If we adopt this, 'what is a sentence and what is not' will be debated again and again at lkml. For each particular sentence. Do you want that? ;)
OTOH 'no trailing dots in logs' rule is simple and not too ugly for any log message.
Signature · 1 line
vda