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 _______________________________________________ sssd-devel mailing list [email protected] https://lists.fedorahosted.org/admin/lists/[email protected]
