Re: [PATCH] 0/3 coding standards documentation/code updates

J. Bruce Fields
2007-09-29T19:56:51Z

On Sat, Sep 29, 2007 at 11:18:05AM -0700, Linus Torvalds wrote:
> I'm not very happy with this.
>
> "CodingStyle" should be about the big issues, not about details. Yes,
> we've messed that up over the years, but let's not continue that.
>
> In other words, I'd suggest *removing* lines from CodingStyle, not adding
> them. The file has already gone from a "good general principles" to "lots
> of stupid details". Let's not make it worse.

It'd be nice to split the current CodingStyle into two documents:

- A shorter CodingStyle that gives the spirit of the style
(short functions, minimal nesting, logic as straightforward as
possible, etc.), and addresses the most commonly repeated
mistakes, without so much detail that people's eyes glaze
over. You want to be able to recommend it to your students
(or whoever) in reasonable confidence that they'll actually
read it and have fun (leave the jokes in!). Currently I'm
suspicious that it's becoming something that everybody
recommends but noone bothers to sit down and read anymore
unless they're working on it.

- A CodingStyleReference that's just a long dry list of rules,
organized to make it easy to look up an individual rule when
needed. That'd also take the pressure of CodingStyle to
accept every new detail.

It'd be a start just to revert CodingStyle to its original content and
move the rest to CodingStyleReference. But someone would want to skim
through the CodingStyle history for any legimate corrections that we
want to keep.

--b.