svn commit: r211501 - in head/sys: modules modules/send netinet netinet6 sys

[Doug Barton]

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