documentation: another proposal to improve our code

[Ira Cooper]

On Sat, Oct 13, 2012 at 6:58 PM, Matthieu Patou <mat at samba.org> 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.

I'm on the other side of this one.

I've worked in code bases with and without it.  I ignore the function
block comments, they are often out of date and/or too vague, in
general.  If I need them, they contain true design data and things
that that, that need to be documented in the code regardless!

"We'll do better." Nobody I've ever worked with has.

If you want to document an external API, great, do it in-line with
function headers.  I 100% recommend that just so the docs stay up to
date.  But for internal code, we have enough code that doesn't even
have in-line comments, the really valuable type, that focusing on
checkmark boilerplate feels useless, and a waste of our time.

It will make us look more busy on ohloh, I guess that's a plus?

-Ira