Skip to contentSkip to conversation

kernel guide to space

DISCUSSION [email protected] 7 participants 13 messages Jul 14, 2005 – Jul 23, 2005

lore
Share & tools
lore
#0 lore raw
Quoted 4 lines
Quoted 1 line

I don't think there's a strict 80 column rule anymore. It's 2005...

Think again. There are a lot of people who use 80 column windows so that we can see two code windows side-by-side.

Agreed. If you're having trouble with width, it's a sign that the code needs to be refactored.

Also, my personal rule is if that a source file exceeds 1000 lines, start looking for a way to split it. It can go longer (indeed, there is little reason to split the fs/nls/nls_cp9??.c files), but
(I will refrain from discussing drivers/scsi/advansys.c)

Comments on the rest of the thread:

Quoted 8 lines

3a. Binary operators

	+ - / * %
	== !=  > < >= <= && || 
	& | ^ << >> 
	= *= /= %= += -= <<= >>= &= ^= |=

	spaces around the operator
	a + b

Generally, yes, and if you violate this, take the spaces out around the tightest-binding operators first!

Quoted 6 lines
Quoted 2 lines

I like this style because I can grep for ^function_style_for_easy_grep and quickly find function def.

That's a pretty bad argument, since most functions aren't declared that way, and there are much better source code navigational tools, like cscope and ctags.

Well, I use that style for everything I write, for exactly that reason, so it's fairly popular. Yes, there are lots of tools, but it's convenient not to need them.

Also, definition argument lists can be a little longer than declaration argument lists (due to the presence of argument names and possible const qualifiers), so an extra place to break the line helps.

And it provides a place to put the handy GCC __attribute__(()) extensions...

static unsigned __attribute__((nonnull, pure)) is_condition_true(struct hairy *p, unsigned priority) {
...
}

Finally, if you are burdened with long argument names, a shorter fixed prefix makes it easier to align the arguments. To pick a real-world example:

static sctp_disposition_t sctp_sf_do_5_2_6_stale(const struct sctp_endpoint *ep,
const struct sctp_association *
asoc,
const sctp_subtype_t type, void *arg, sctp_cmd_seq_t *commands)
I prefer to write

static sctp_disposition_t sctp_sf_do_5_2_6_stale(const struct sctp_endpoint *ep,
const struct sctp_association *asoc, const sctp_subtype_t type, void *arg,
sctp_cmd_seq_t *commands)
Although in extreme cases, it's usually best to just to:
static sctp_disposition_t sctp_sf_do_5_2_6_stale_bug_workaround(
const struct sctp_endpoint *ep,
const struct sctp_association *asoc,
const sctp_subtype_t type,
void *arg,
sctp_cmd_seq_t *commands)

Quoted 5 lines
Quoted 3 lines

3e. sizeof
space after the operator
sizeof a

I use sizeof(a) always (both for sizeof(type) and sizeof(expr)).

You can, but I prefer not to. Still, it behaves a lot "like a function", so it's not too wrong. In fact, I'll usually avoid the sizeof(type) version entirely. It's often clearer to replace, e.g.

	char buffer[sizeof(struct sctp_errhdr)+sizeof(union sctp_addr_param)];
with
	char buffer[sizeof *errhdr + sizeof *addrparm];

which (if you look at the code in sctp_sf_send_restart_abort), actually reflects what's going on better.

What really gets my goat is

	return(0);

return *is not a function*. Stop making it look syntactically like one! That should be written

	return 0;
Quoted 4 lines
Quoted 4 lines

3i. if/else/do/while/for/switch
space between if/else/do/while and following/preceeding statements/expressions, if any:

Quoted 8 lines
Quoted 6 lines
	if (a) {
	} else {
	}

	do {
	} while (b);

What's wrong with if(expr) ? Rationale?

- It's less visually distinct from a function call.
- The space makes the keyword (important things, keywords) stand out more and makes it easier to pick out of a mass of code.
- (Subjective) it balances the space in the trailing ") {" better.

This matches my personal style.

Quoted 6 lines
Quoted 3 lines

6. One-line statement does not need a {} block, so dont put it into one

	if (foo)
		bar;

Disagree. Common case of hard-to-notice bug:

Quoted 8 lines
	if(foo)
		bar()
...after some time code evolves into:
	if(foo)
		/*
		 * We need to barify it, or else pagecache gets FUBAR'ed
		 */
		bar();

The braces should have been added then. They are okay to omit when the body contains one physical line of text, but my rule is that a comment or broken expression requires braces:

	if (foo) {
		/* We need to barify it, or else pagecache gets FUBAR'ed */
		bar();
	}

	if (foo) {
		bar(p->foo[hash(garply) % LARGEPRIME]->head,
		    flags & ~(FLAG_FOO | FLAG_BAR | FLAG_BAZ | FLAG_QUUX));
	}
Quoted 6 lines

Thus we may be better to slighty encourage use of {}s even if they are not needed:

	if(foo) {
		bar();
	}

It's not horrible to include them, but it reduces clutter sometimes to leave them out.

Quoted 11 lines
Quoted 4 lines
	if (foobar(.................................) + barbar * foobar(bar +
	                                                                foo *
	                                                                oof)) {
	}

Ugh, that's as ugly as it can get... Something like below is much easier to read...

	if (foobar(.................................) +
	    barbar * foobar(bar + foo * oof)) {
	}

Strongly agreed! If you have to break an expression, do it at the lowest precedence point possible!

Quoted 7 lines

Even easier is

	if (foobar(.................................)
	    + barbar * foobar(bar + foo * oof)) {
	}

Since a statement cannot start with binary operators
and as such we are SURE that there must have been something before.

I don't tend to do this, but I see the merit. However, C uses a number of operators (+ - * &) in both unary and binary forms, so it's not always unambiguous.

In such cases, I'll usually move the brace onto its own line to make the end of the condition clearer:

	if (foobar(.................................) +
	    barbar * foobar(bar + foo * oof))
	{
	}

Of course, better yet is to use a temporary or something to shrink the condition down to a sane size, but sometimes you just need

	if (messy_condition_one &&
	    messy_condition_two &&
	    messy_condition_three)
	{
	}
#1 lore raw
Quoted 5 lines · On Jul 13, 2005, at 21:12:08, [email protected] wrote:
Quoted 4 lines
Quoted 1 line

I don't think there's a strict 80 column rule anymore. It's 2005...

Think again. There are a lot of people who use 80 column windows so that we can see two code windows side-by-side.

Quoted 7 lines

Agreed. If you're having trouble with width, it's a sign that the code needs to be refactored.

Also, my personal rule is if that a source file exceeds 1000 lines, start looking for a way to split it. It can go longer (indeed, there is little reason to split the fs/nls/nls_cp9??.c files), but
(I will refrain from discussing drivers/scsi/advansys.c)

A simple set of code refactoring rules that I try to abide by:

1) If a function is more than a few 25 or 40 line screens, it's likely too big (unless a big switch statement or a list of initialization calls or something). If necessary, use static inline functions to factor out repetitive behavior.

2) If a file is more than 30-40 functions, it's likely too big, and you should try to split it. It's _ok_ to have 4 source files implementing code for manipulating a single struct.

3) If a normal line of code is more than 80 characters, one of the following is probably true: you need to break the line up and use temps for clarity, or your function is so big that you're tabbing over too far.

Cheers,
Kyle Moffett

-----BEGIN GEEK CODE BLOCK-----
Version: 3.12
GCM/CS/IT/U d- s++: a18 C++++>$ UB/L/X/*++++(+)>$ P+++(++++)>$ L++++(+++) E W++(+) N+++(++) o? K? w--- O? M++ V? PS+() PE+(-) Y+ PGP+++ t+(+++) 5 X R? tv-(--) b++++(++) DI+ D+ G e->++++$ h!*()>++$ r !y?(-) ------END GEEK CODE BLOCK------

#2 lore raw
Quoted 5 lines

3) If a normal line of code is more than 80 characters, one of the following is probably true: you need to break the line up and use temps for clarity, or your function is so big that you're tabbing over too far.

(Find source files, expand tab chars to their on-screen length, print if

Quoted 1 line

= 80, count lines)

~/linux-2.6.12 >
find . -type f "(" -iname "*.c" -o -iname "*.h" -o -iname "*.S" ")" -print0 | xargs -0 perl -pe '1 while s/\t+/" "x(length($&)*8-length($`)%8)/e' | \
perl -ne 'print if/.{80}/' | \
wc -l
208420

If the indent was just 4 spc wide, the number of extending lines is just 131925.

Jan Engelhardt

#3 lore raw
Quoted 2 lines · Jan

(Find source files, expand tab chars to their on-screen length, print if

Quoted 1 line

= 80, count lines)

The bulk of the longest lines are in the sound and drivers subtrees.

One example on the "high end", with 546 chars in one line:

==

drivers/scsi/BusLogic.c:

  %2d	 %5d %5d %5d    %5d %5d %5d	   %5d %5d %5d\n", TargetID, TargetStatistics[TargetID].CommandAbortsRequested, TargetStatistics[TargetID].CommandAbortsAttempted, TargetStatistics[TargetID].CommandAbortsCompleted, TargetStatistics[TargetID].BusDeviceResetsRequested, TargetStatistics[TargetID].BusDeviceResetsAttempted, TargetStatistics[TargetID].BusDeviceResetsCompleted, TargetStatistics[TargetID].HostAdapterResetsRequested, TargetStatistics[TargetID].HostAdapterResetsAttempted, TargetStatistics[TargetID].HostAdapterResetsCompleted);

==

Clearly, it would be unrepresentative of certain coding styles in drivers and sound to claim they closely followed an 80 column constraint.

Perhaps the spacing guide should acknowledge this, with some qualification such as:

The core kernel code (as apposed to some driver code) tends to keep source line lengths below 80 columns. When changing such code, respect the line length constraints of nearby code.

Signature · 3 lines
                  I won't rest till it's the best ...
                  Programmer, Linux Scalability
                  Paul Jackson <[email protected]> 1.925.600.0401
#4 lore raw
Quoted 11 lines
Quoted 3 lines

(Find source files, expand tab chars to their on-screen length, print if

Quoted 1 line

= 80, count lines)

The bulk of the longest lines are in the sound and drivers subtrees. One example on the "high end", with 546 chars in one line:

==
drivers/scsi/BusLogic.c:
%2d %5d %5d %5d %5d %5d %5d %5d %5d %5d\n", TargetID, TargetStatistics[TargetID].CommandAbortsRequested, TargetStatistics[TargetID].CommandAbortsAttempted, TargetStatistics[TargetID].CommandAbortsCompleted, TargetStatistics[TargetID].BusDeviceResetsRequested, TargetStatistics[TargetID].BusDeviceResetsAttempted, TargetStatistics[TargetID].BusDeviceResetsCompleted, TargetStatistics[TargetID].HostAdapterResetsRequested, TargetStatistics[TargetID].HostAdapterResetsAttempted, TargetStatistics[TargetID].HostAdapterResetsCompleted);
==

this is omg.
- the VLN BASIC way (very long variable names)
- it could have been splitted at the next possible space at 80, i.e. mostly after a comma (my mail _reader_ automatically wrapped it, so it looked rather ok - until I took an _editor_)

If I add a temporary (as suggested by rule 3)
(struct BusLogic_Statistics *tp = &TargetStatistics[TargetID]), the line length loses a lot of weight: 339 chars.

Quoted 1 line

%2d %5d %5d %5d %5d %5d %5d %5d %5d %5d\n", TargetID, TargetStatistics[TargetID].CommandAbortsRequested, TargetStatistics[TargetID].CommandAbortsAttempted, TargetStatistics[TargetID].CommandAbortsCompleted, TargetStatistics[TargetID].BusDeviceResetsRequested, TargetStatistics[TargetID].BusDeviceResetsAttempted, TargetStatistics[TargetID].BusDeviceResetsCompleted, TargetStatistics[TargetID].HostAdapterResetsRequested, TargetStatistics[TargetID].HostAdapterResetsAttempted, TargetStatistics[TargetID].HostAdapterResetsCompleted);

Jan Engelhardt

#5 lore raw
In reply to Paul Jackson
Quoted 4 lines · Paul Jackson

drivers/scsi/BusLogic.c:

%2d %5d %5d %5d %5d %5d %5d %5d %5d %5d\n",
TargetID, TargetStatistics[TargetID].CommandAbortsRequested, TargetStatistics[TargetID].CommandAbortsAttempted, TargetStatistics[TargetID].CommandAbortsCompleted, TargetStatistics[TargetID].BusDeviceResetsRequested, TargetStatistics[TargetID].BusDeviceResetsAttempted, TargetStatistics[TargetID].BusDeviceResetsCompleted, TargetStatistics[TargetID].HostAdapterResetsRequested, TargetStatistics[TargetID].HostAdapterResetsAttempted, TargetStatistics[TargetID].HostAdapterResetsCompleted);

Ugh!!! From CodingStyle (although this is not always followed):

Quoted 6 lines

The limit on the length of lines is 80 columns and this is a hard limit. 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. [example relevant to the above code snipped]

Also:

Quoted 7 lines

C is a Spartan language, and so should your naming be. Unlike Modula-2 and Pascal programmers, C programmers do not use cute names like ThisVariableIsATemporaryCounter. A C programmer would call that variable "tmp", which is much easier to write, and not the least more difficult to understand.

[...] mixed-case names are frowned upon [...]

*cough* TargetStatistics[TargetID].HostAdapterResetsCompleted *cough*

I suspect linus would be willing to accept a few cleanup patches for the BusLogic.c file. Perhaps even one that renames BusLogic.c to buslogic.c like all the other files in the source tree, instead of using nasty StudlyCaps all over :-D

Cheers,
Kyle Moffett

-----BEGIN GEEK CODE BLOCK-----
Version: 3.12
GCM/CS/IT/U d- s++: a18 C++++>$ UB/L/X/*++++(+)>$ P+++(++++)>$ L++++(+++) E W++(+) N+++(++) o? K? w--- O? M++ V? PS+() PE+(-) Y+ PGP+++ t+(+++) 5 X R? tv-(--) b++++(++) DI+ D+ G e->++++$ h!*()>++$ r !y?(-) ------END GEEK CODE BLOCK------

#6 lore raw
Quoted 1 line · Kyle Moffett

On Jul 20, 2005, at 20:45:21, Paul Jackson wrote:

[...snip...]

Quoted 7 lines

*cough* TargetStatistics[TargetID].HostAdapterResetsCompleted *cough*

I suspect linus would be willing to accept a few cleanup patches for the BusLogic.c file. Perhaps even one that renames BusLogic.c to buslogic.c like all the other files in the source tree, instead of using nasty StudlyCaps all over :-D

To avoid people doing duplicate work, I just want to say that I've started doing a CodingStyle/whitespace/VariableAndFunctionNaming cleanup of the BusLogic driver, I'll send the patches to LKML in a few hours.

Signature · 3 lines
Jesper Juhl <[email protected]>
Don't top-post  http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please      http://www.expita.com/nomime.html
#7 lore raw
Quoted 11 lines · Jesper Juhl
Quoted 1 line · Kyle Moffett

On Jul 20, 2005, at 20:45:21, Paul Jackson wrote:

[...snip...]

Quoted 7 lines

*cough* TargetStatistics[TargetID].HostAdapterResetsCompleted *cough*

I suspect linus would be willing to accept a few cleanup patches for the BusLogic.c file. Perhaps even one that renames BusLogic.c to buslogic.c like all the other files in the source tree, instead of using nasty StudlyCaps all over :-D

Quoted 5 lines

To avoid people doing duplicate work, I just want to say that I've started doing a CodingStyle/whitespace/VariableAndFunctionNaming cleanup of the BusLogic driver, I'll send the patches to LKML in a few hours.

Are you going to get rid of the BusLogic* in front of every variable and function name? (yes please??) If so, you will need a few days!

It will take probably an hour to parse:
struct BusLogic_FetchHostAdapterLocalRAMReguest FetchHostAdapterLocalRAMRequest
^!)

Quoted 4 lines

--
Jesper Juhl <[email protected]>
Don't top-post http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please http://www.expita.com/nomime.html

Cheers,
Dick Johnson
Penguin : Linux version 2.6.12 on an i686 machine (5537.79 BogoMips).
Notice : All mail here is now cached for review by Dictator Bush.
98.36% of all statistics are fiction.

****************************************************************
The information transmitted in this message is confidential and may be privileged. Any review, retransmission, dissemination, or other use of this information by persons or entities other than the intended recipient is prohibited. If you are not the intended recipient, please notify Analogic Corporation immediately - by replying to this message or by sending an email to [email protected] - and destroy all copies of this information, including any attachments, without reading or disclosing them.

Thank you.

#8 lore raw
Quoted 14 lines · linux-os (Dick Johnson)
Quoted 11 lines · Jesper Juhl
Quoted 1 line · Kyle Moffett

On Jul 20, 2005, at 20:45:21, Paul Jackson wrote:

[...snip...]

Quoted 7 lines

*cough* TargetStatistics[TargetID].HostAdapterResetsCompleted *cough*

I suspect linus would be willing to accept a few cleanup patches for the BusLogic.c file. Perhaps even one that renames BusLogic.c to buslogic.c like all the other files in the source tree, instead of using nasty StudlyCaps all over :-D

Quoted 7 lines
Quoted 5 lines

To avoid people doing duplicate work, I just want to say that I've started doing a CodingStyle/whitespace/VariableAndFunctionNaming cleanup of the BusLogic driver, I'll send the patches to LKML in a few hours.

Are you going to get rid of the BusLogic* in front of every variable and function name? (yes please??)

Yes, I am.

Quoted 1 line

If so, you will need a few days!

That may be, it sure turned into a bigger job than I had at first expected. I'll break it into a few logical bits and submit them along the way. First bits in a few hours - let's see how far I get :)

Quoted 2 lines

It will take probably an hour to parse:
struct BusLogic_FetchHostAdapterLocalRAMReguest

Yeah, it takes time, but I'll get it done.

Quoted 3 lines

Thank you.

np.

Signature · 3 lines
Jesper Juhl <[email protected]>
Don't top-post  http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please      http://www.expita.com/nomime.html
#9 lore raw
Quoted 31 lines · Jesper Juhl
Quoted 14 lines · linux-os (Dick Johnson)
Quoted 11 lines · Jesper Juhl
Quoted 1 line · Kyle Moffett

On Jul 20, 2005, at 20:45:21, Paul Jackson wrote:

[...snip...]

Quoted 7 lines

*cough* TargetStatistics[TargetID].HostAdapterResetsCompleted *cough*

I suspect linus would be willing to accept a few cleanup patches for the BusLogic.c file. Perhaps even one that renames BusLogic.c to buslogic.c like all the other files in the source tree, instead of using nasty StudlyCaps all over :-D

Quoted 7 lines
Quoted 5 lines

To avoid people doing duplicate work, I just want to say that I've started doing a CodingStyle/whitespace/VariableAndFunctionNaming cleanup of the BusLogic driver, I'll send the patches to LKML in a few hours.

Are you going to get rid of the BusLogic* in front of every variable and function name? (yes please??)

Yes, I am.

Quoted 1 line

If so, you will need a few days!

That may be, it sure turned into a bigger job than I had at first expected. I'll break it into a few logical bits and submit them along the way. First bits in a few hours - let's see how far I get :)

Quoted 5 lines
Quoted 2 lines

It will take probably an hour to parse:
struct BusLogic_FetchHostAdapterLocalRAMReguest

Yeah, it takes time, but I'll get it done.

Heh, it takes a little more time than I had anticipated. I've got ~300Kb of patches here already, and I'm only about 30% done (estimated).
It makes little sense to post the patches I have at this time, since they don't really finish the job and leave the files in a funky intermediate state, so I'll hold off on posting them untill I'm a little closer to the goal - hopefully tomorrow I'll finish it (right now I need to get some sleep) - I'll post the patches as soon as I'm done with them...

Signature · 3 lines
Jesper Juhl <[email protected]>
Don't top-post  http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please      http://www.expita.com/nomime.html
#10 lore raw
Quoted 37 lines · Jesper Juhl
Quoted 31 lines · Jesper Juhl
Quoted 14 lines · linux-os (Dick Johnson)
Quoted 11 lines · Jesper Juhl
Quoted 1 line · Kyle Moffett

On Jul 20, 2005, at 20:45:21, Paul Jackson wrote:

[...snip...]

Quoted 7 lines

*cough* TargetStatistics[TargetID].HostAdapterResetsCompleted *cough*

I suspect linus would be willing to accept a few cleanup patches for the BusLogic.c file. Perhaps even one that renames BusLogic.c to buslogic.c like all the other files in the source tree, instead of using nasty StudlyCaps all over :-D

Quoted 7 lines
Quoted 5 lines

To avoid people doing duplicate work, I just want to say that I've started doing a CodingStyle/whitespace/VariableAndFunctionNaming cleanup of the BusLogic driver, I'll send the patches to LKML in a few hours.

Are you going to get rid of the BusLogic* in front of every variable and function name? (yes please??)

Yes, I am.

Quoted 1 line

If so, you will need a few days!

That may be, it sure turned into a bigger job than I had at first expected. I'll break it into a few logical bits and submit them along the way. First bits in a few hours - let's see how far I get :)

Quoted 5 lines
Quoted 2 lines

It will take probably an hour to parse:
struct BusLogic_FetchHostAdapterLocalRAMReguest

Yeah, it takes time, but I'll get it done.

Quoted 10 lines

Heh, it takes a little more time than I had anticipated. I've got ~300Kb of patches here already, and I'm only about 30% done (estimated).
It makes little sense to post the patches I have at this time, since they don't really finish the job and leave the files in a funky intermediate state, so I'll hold off on posting them untill I'm a little closer to the goal - hopefully tomorrow I'll finish it (right now I need to get some sleep) - I'll post the patches as soon as I'm done with them...

Still moving forward with this, but not yet done. I think I'm going to need one more day to finish this.

Signature · 3 lines
Jesper Juhl <[email protected]>
Don't top-post  http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please      http://www.expita.com/nomime.html
#11 lore raw
In reply to linux-os (Dick Johnson)
Quoted 3 lines · linux-os \(Dick Johnson\)

It will take probably an hour to parse:
struct BusLogic_FetchHostAdapterLocalRAMReguest FetchHostAdapterLocalRAMRequest
^!)

Agh! My eyes!

The above names are way overdone by any measure, but is there any consensus whether studly-caps in general are discouraged or not?

CodingStyle is vague on the issue, though it kind of implies you should use underscores when multiple words are needed (the sole example of studly caps is in a negative context, and a following recommended name uses underlines). The kernel source seems pretty random -- they get used here and there, but more often not; they seem more common in older code.

If they are discouraged, it might be better to say so explicitly, as there are many programmers these days who are used to using them.

-Miles

Signature · 1 line
Run away!  Run away!
#12 lore raw
Quoted 1 line · Miles

CodingStyle is vague on the issue, though ...

Perhaps we should call it "coding_style" <grin>.

Signature · 3 lines
                  I won't rest till it's the best ...
                  Programmer, Linux Scalability
                  Paul Jackson <[email protected]> 1.925.600.0401