documentation: another proposal to improve our code

[simo]

On Sat, 2012-10-13 at 15:58 -0700, Matthieu Patou wrote:
> Hello all,
> 
> It seems that we are in a period of proposal so here is my proposal to 
> improve the quality of the project, make review much much much more 
> easier, lower the bar for non team member to commit: make documentation 
> of each function mandatory.
> 
> That is to say each function that is created and if you modify a 
> function that hasn't any documentation you add it too.
> I suppose that I don't need to explain the advantage of this, but still 
> I'll do it :-)
> 
> Lately I've been doing a lot of fixes in DRS code and now in ACLs, it's 
> non trivial code and sometime the function name didn't give a clue of 
> what's going on having documentation helps to figure out what's going on 
> and so helps to make more easily modification. For new comers it's even 
> more important due to the fact that the code is pretty vast and not 
> everybody has 15+ years of history with this code (like tridge or jeremy).
> 
> Also I would like to indicate that I praise (silently but still) the 
> work Andreas has done on talloc and other libraries that makes life much 
> more easier.
> 
> I know that adding documentation is a big task that's why we could start 
> with just the new functions as when you are writing code it shouldn't be 
> super hard to spend 5 more minutes (or sometimes even less) to explain 
> what the function does in comparison to the time spent on coding itself 
> it should be negligible.
> I propose that we start this for every new commit on a voluntary basis 
> and see how it goes in one month.
> For the most motivated on I proposed to try the full set right now, but 
> I can understand that it then tries to take (much?) more time than the 
> coding.

+1 totally agree, and feel free to NACK any patch that comes from myself
and doesn't respect this rule, even if it is not adopted as a hard rule.
 
Simo.

-- 
Simo Sorce
Samba Team GPL Compliance Officer <simo at samba.org>
Principal Software Engineer at Red Hat, Inc. <simo at redhat.com>