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

["J. Bruce Fields" <bfields@fieldses.org>]

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.