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

Garrett Cooper yanegomi at gmail.com
Sat Oct 15 23:22:16 UTC 2011


On Sat, Oct 15, 2011 at 3:53 PM, Benjamin Kaduk <kaduk at mit.edu> wrote:
> On Fri, 14 Oct 2011, Garrett Cooper wrote:
>
>> 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.
>
> No arguments, here.
> (Well, except for Garrett's mailer's mangling of the whitespace ...)

I think we can all agree that Gmail is pretty braindead when used from
the web interface..
-Garrett



More information about the freebsd-doc mailing list