Date: Sat, 21 Aug 2010 14:15:45 -0700 (PDT) From: Doug Barton <dougb@FreeBSD.org> To: Rui Paulo <rpaulo@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: <alpine.BSF.2.00.1008211409420.1942@qbhto.arg> In-Reply-To: <BA312DC6-878D-440F-95C6-4E8F50F75802@FreeBSD.org> 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>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sat, 21 Aug 2010, Rui Paulo wrote: > On 21 Aug 2010, at 19:20, Doug Barton wrote: > >> 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. >>> >>> 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. >> >> 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? > > By writing man pages...? 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." 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. Doug -- Improve the effectiveness of your Internet presence with a domain name makeover! http://SupersetSolutions.com/ Computers are useless. They can only give you answers. -- Pablo Picasso
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.BSF.2.00.1008211409420.1942>