Hi Pavel,
Thank you for your thoughtful and weighted response.
Please see my comments below.
On 07/25/2016 11:56 AM, Pavel Březina wrote:
Hi Nick,
when I joined SSSD I used to document everything, exactly the way you
do. But I was trained by Jakub not to do it and in time I started to see
benefits of documenting only public interface that is bound to be stale.
Maintaining documentation is a pain and core developer doesn't need it
since we can understand most of the code quite quickly and we rewrite
the poor parts we don't.
I understand. However, this creates a closed-in culture with a high price of
entry. Which is still higher for people who (feel they) can't approach and
talk to us.
Is it worth paying for a person who just wants a couple fixes or small
features done and doesn't want to become a full-time developer?
However, I can see the benefits of code documentation for new comers.
So
the question is, would this help us to attract more contributors? Or is
SSSD already too complicated for any ordinary coder to step in? I'm
afraid its the latter, since serious development requires lots of
knowledge in both outside and inside SSSD that simply don't come in a
few days.
I'm sure that documentation would lower the barrier to entry. Yes, SSSD is
complicated, but not writing documentation wouldn't make it easier to
understand. The question is how many people trying to modify it give up, and
whether we can lower that number.
We have a hard time understanding it ourselves, and we can ask each other and
tap the sacred folklore. People outside don't have that privilege, or don't
feel they have.
Do you have an example of a project that gained more contributors
after
creating a documentation?
Nope, I don't have any concrete evidence.
I personally see more benefit in writing articles on how SSSD works
(we
already have some) and on our coding habits (e.g. EAGAIN mean
asynchronous processing) than in documenting code.
Such documentation seems good precisely because it's so removed from the code.
Yes, it needs changing rarely, but it's also much less useful for a person
wanting to change a specific piece of code, as compared to becoming a general
developer.
Unfortunately, you chose probably the worse code for start that you
could possible choose. NSS responder is one of the oldest code that I
admit is terrible to read and contains lots of per-feature hacks.
Yes, it's pretty hard to read and that made me really wish for documentation.
But as you dig in, you see that most of the code is just about
reading data
from cache and refreshing them in providers. All this complexity can be now
done with one call of cache_req. Since you have the code in grasp, would you
like to convert it to cache_req please?
I would like to do that, but I have a lot of urgent work to do on Session
Recording project, sorry. I'll try to sneak some minor improvements in,
though.
To summarize, yes, once you get into it, once you talk to people, figure out
all the ideas, read the code again and again, get through a couple reviews,
etc., you can live without documentation. However, most potential (occasional)
contributors can't afford that.
And, yes, code documentation is only one variable in the equation of getting
the contributors. It is not a panacea, it only helps so much. Yet, it also
increases engineering discipline (a hacked-together code is harder to
document), and improves and speeds up understanding of the code for core
developers too.
We were all newbies with this or other projects (I still am one) and we
remember the pain. Do we want our contributors to feel that too?
Nick