Date: Sat, 21 Aug 2010 22:48:46 +0100 From: Rui Paulo <rpaulo@FreeBSD.org> To: Doug Barton <dougb@FreeBSD.org> Cc: svn-src-head@FreeBSD.org, Ana Kukec <anchie@FreeBSD.org>, svn-src-all@FreeBSD.org, "Bjoern A. Zeeb" <bz@FreeBSD.org>, src-committers@FreeBSD.org Subject: Re: svn commit: r211501 - in head/sys: modules modules/send netinet netinet6 sys Message-ID: <26CBB559-FA72-4688-92E9-ED9CEA151B2C@FreeBSD.org> In-Reply-To: <alpine.BSF.2.00.1008211409420.1942@qbhto.arg> References: <201008191131.o7JBV4Yf002412@svn.freebsd.org> <4C6D18BE.2000905@fer.hr> <4C6D95A8.9070105@FreeBSD.org> <20100819213159.B48418@maildrop.int.zabbadoz.net> <4C6DDB74.3090102@FreeBSD.org> <7186318F-0921-41E5-9641-3D6B45E0623B@FreeBSD.org> <4C701901.8030505@FreeBSD.org> <BA312DC6-878D-440F-95C6-4E8F50F75802@FreeBSD.org> <alpine.BSF.2.00.1008211409420.1942@qbhto.arg>
next in thread | previous in thread | raw e-mail | index | archive | help
On 21 Aug 2010, at 22:15, Doug Barton wrote: > On Sat, 21 Aug 2010, Rui Paulo wrote: >=20 >> On 21 Aug 2010, at 19:20, Doug Barton wrote: >>=20 >>> On 08/21/2010 05:07, Rui Paulo wrote: >>>>> Meanwhile, the fact that in the past code has been committed >>>>> without man pages is the exact cause of the problem you're >>>>> describing. It is certainly not a justification for continuing to >>>>> do it wrong. >>>>=20 >>>> Reverting code just because it doesn't have a man page is = pointless. >>>> Everyone can write the damn man page, but not everyone can write >>>> code. You should really take this into consideration when proposing = a >>>> commit to be reverted. >>>=20 >>> So let's assume that having lots of code in the tree without a man = page is a problem. Further, let's assume that we don't want the problem = to get worse. How do you propose that we accomplish that? >>=20 >> By writing man pages...? >=20 > But that's the status quo (I.e., hope that people will/eventually = write man pages for stuff) and it hasn't worked so far. The situation = isn't actually going to be improved until we make a change. A simple = (and I think abundantly reasonable) change that we can make today is, = "Don't allow new work to be committed without a man page." >=20 > Meanwhile, there are a lot of benefits to this idea above and beyond = the obvious one of having man pages for stuff. The biggest single = benefit is that actually writing documentation for things forces you to = re-examine assumptions, work through non-obvious and/or non-default code = paths, etc. Speaking for myself, it's happened on more than one occasion = that as I sit down to document some piece of code I realize that there = are either bugs, or at least a better way of doing something. Requiring = developers to work through this process before code goes into the tree = gets us better code in addition to documentation. If your concern is to change the status quo, you do understand that you = picked the worst possible thread to hijack ? Esp. since the author = promised to roll out a man page. Regards, -- Rui Paulo
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?26CBB559-FA72-4688-92E9-ED9CEA151B2C>