documentation: another proposal to improve our code

simo idra at samba.org
Mon Oct 15 08:27:02 MDT 2012


On Mon, 2012-10-15 at 16:15 +0200, Volker Lendecke wrote:
> On Sun, Oct 14, 2012 at 09:01:36PM -0700, Jeremy Allison wrote:
> > On Sat, Oct 13, 2012 at 03:58:07PM -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.
> > > 
> > > 
> > > Please comment.
> > 
> > +1 - excellent idea !
> 
> For the tevent_req continuation functions I would like to
> have an exception. _send and _recv -- sure, but doing the
> same for all the _done function which I try to name very
> verbosely, I don't know if describing "subreq" parameter
> and the void return value over and over again gives much
> additional value.


Ack I think we should have a special policy on how to document
tevent_req style sequences.

We should probably have just one doxygen comment for the whole sequence,
as the sequence is de facto a single function and it is split in parts
just for technical reasons.

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



More information about the samba-technical mailing list