Date: Fri, 14 Oct 2011 00:37:29 -0600 (MDT) From: Warren Block <wblock@wonkity.com> To: Garrett Cooper <yanegomi@gmail.com> Cc: Niclas Zeising <niclas.zeising@gmail.com>, freebsd-doc@freebsd.org Subject: Re: docs/160696: style(9) should be mentioned in the devs' handbook Message-ID: <alpine.BSF.2.00.1110140007150.51585@wonkity.com> In-Reply-To: <CAGH67wQBtWPYKMURtd0mp4HnZC3gn3pg2GHu0wK%2BZjg-DtL5-Q@mail.gmail.com> References: <201110121030.p9CAUDxd032245@freefall.freebsd.org> <alpine.GSO.1.10.1110132355240.882@multics.mit.edu> <alpine.BSF.2.00.1110132212210.51180@wonkity.com> <CAGH67wQBtWPYKMURtd0mp4HnZC3gn3pg2GHu0wK%2BZjg-DtL5-Q@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
This message is in MIME format. The first part should be readable text, while the remaining parts are likely unreadable without MIME-aware tools. ---902635197-1056568125-1318574249=:51585 Content-Type: TEXT/PLAIN; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 8BIT On Thu, 13 Oct 2011, Garrett Cooper wrote: > On Thu, Oct 13, 2011 at 9:13 PM, Warren Block <wblock@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> 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> ---902635197-1056568125-1318574249=:51585--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.BSF.2.00.1110140007150.51585>