documentation: another proposal to improve our code

[Jelmer Vernooij]

On Sat, Oct 13, 2012 at 03:58:07PM -0700, Matthieu Patou wrote:
> 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.

Can we do this after we've resolved the conversation about mandatory
code review?  Having two discussions and two experiments going on at
the same time is a distraction, and makes it harder to evaluate the
results of the experiments.

Cheers,

Jelmer