From owner-svn-src-head@FreeBSD.ORG Sat Aug 21 21:15:49 2010 Return-Path: Delivered-To: svn-src-head@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id EA34410656AB for ; Sat, 21 Aug 2010 21:15:49 +0000 (UTC) (envelope-from dougb@FreeBSD.org) Received: from mail2.fluidhosting.com (mx21.fluidhosting.com [204.14.89.4]) by mx1.freebsd.org (Postfix) with ESMTP id 89E078FC1D for ; Sat, 21 Aug 2010 21:15:49 +0000 (UTC) Received: (qmail 7402 invoked by uid 399); 21 Aug 2010 21:15:47 -0000 Received: from localhost (HELO laptop.dougb.net) (dougb@dougbarton.us@127.0.0.1) by localhost with ESMTPAM; 21 Aug 2010 21:15:47 -0000 X-Originating-IP: 127.0.0.1 X-Sender: dougb@dougbarton.us Date: Sat, 21 Aug 2010 14:15:45 -0700 (PDT) From: Doug Barton To: Rui Paulo In-Reply-To: Message-ID: 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> User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) X-message-flag: Outlook -- Not just for spreading viruses anymore! OpenPGP: id=1A1ABC84 Organization: http://SupersetSolutions.com/ MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed Cc: svn-src-head@FreeBSD.org, Ana Kukec , svn-src-all@FreeBSD.org, "Bjoern A. Zeeb" , src-committers@FreeBSD.org Subject: Re: svn commit: r211501 - in head/sys: modules modules/send netinet netinet6 sys X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 21 Aug 2010 21:15:50 -0000 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