docs/160696: style(9) should be mentioned in the devs' handbook

[Garrett Cooper]

On Thu, Oct 13, 2011 at 11:37 PM, Warren Block <wblock at wonkity.com> wrote:
> On Thu, 13 Oct 2011, Garrett Cooper wrote:
>
>> On Thu, Oct 13, 2011 at 9:13 PM, Warren Block <wblock at wonkity.com> wrote:
>>>
>>> On Fri, 14 Oct 2011, Benjamin Kaduk wrote:
>>>
>>>> The overall paragraph feels a bit odd, though; maybe like it's written
>>>> in
>>>> a more informal style than I would expect?  A more standard dry,
>>>> technical
>>>> writing version might be:
>>>> %%%%%%%%%%
>>>> <para>When working in a large codebase such as the &os; source, it is
>>>> important to adhere to a common coding style.  This provides uniformity
>>>
>>>               ^^^^^^
>>> "conform" might be better here.
>>
>> I'm usually not touchy feely about wording like this, but unless the
>> rest of the document is worded in such a standoffish / cold manner, I
>> would just keep things polite and neutral. "Conform" sounds really
>> pushy and "When working in a..." sounds condescending in my opinion.
>
> Here's a rewrite:
>
> <para>Consistent coding style is extremely important, particularly with
>  large projects like &os;.  Code should follow the &os; coding styles
>  described in &man.style.9;, and &man.style.Makefile.5;.</para>

Sounds ok.

> As an alternate:
>
> <para>We know you've developed some fancy coding style of your own.  So
>  has everybody else.  Hundreds of people, maybe even thousands, have
>  contributed to &os;, and mixing all those different styles results in
>  a mess.  So we're sorry, but do it as shown in &man.style.9;  and
>  &man.style.Makefile.5; if you want your code to be accepted.</para>

:].