svn commit: r211501 - in head/sys: modules modules/send netinet
dougb at FreeBSD.org
Sat Aug 21 21:15:50 UTC 2010
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.
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
More information about the svn-src-all