Re: [eigen] random thoughts -- we need more Gaels

[Benoit Jacob <jacob.benoit.1@xxxxxxxxx>]

2010/10/3 Rui Maciel <rui.maciel@xxxxxxxxx>:
>
> Benoit Jacob wrote:
>> 2010/10/3 Rui Maciel <rui.maciel@xxxxxxxxx>:
>> > Cyrille isn't the only one affectd by this problem.  Countless others,
>> > just like Cyrille, have looked into this project's code with the
>> > intention to contribute fixes and/or implement new features.
>> >  Unfortunately, as this project is terribly developer-unfriendly,
>>
>> you can't call Eigen terribly developer-unfriendly, that's not fair.
>> It just requires both good c++ templates skills and good math skills,
>> which makes a high barried to entry.
>
> Not quite.  Those who take the time to look into the source code tend to know
> C++ and math.  After all, if they knew nothing about that

The issue, is precisely that knowing C++ is not all-or-nothing!
Contrary to most other languages, practically nobody knows enough C++
that he wouldn't have something new to learn from time to time. I
learnt much of what I know about C++ while doing Eigen. I think that
we can actually turn this into a strength, if we play this card well:
"join Eigen development, you'll learn a lot of C++ with us". Then
again, this relies on developer documentation getting written.

> The main cause for the lack of contributions being made to Eigen is the fact
> that it is unfriendly to developers, in the sense that it imposes a barrier to
> entry which is set needlessly high.  For example, it doesn't provide any
> documentation regarding fundamental stuff such as how the library is organized
> or how to implement new features such as new solvers and/or matrix types, stuff
> which will otherwise take weeks of sifting through the source code just to get
> a general ideal of how things are done.

Yes, I agree, this is part of what I mean when I say we need developer
documentation. We agree.

> That is exactly the point.  If the objective is to attract developers then the
> complete lack of any developer-oriented docs constitutes a massive barrier to
> entry.  If a developer decides that he wants to contribute to Eigen and starts
> investing his time to try to get the feel of how Eigen is organized then he
> will be forced to spend a considerable chunk of his time just to try to figure
> that out.  If we add the fact that a considerable number of source files aren't
> even commented

I don't believe that much in heavy commenting. I'd rather start
writing good developer documentation and from there we only
occasionnally lack commenting. Most of our code is self-explanatory to
someone who understands our general design. An example of what I
consider to have the right amount of commenting is
Eigen/src/Core/Assign.h.

Eigen wasn't any more commented when Gael joined --- it was just much
smaller (1000 LOC), so it was possible for him to grasp the overall
design without documentation.

Benoit