Developers of Sympa

[Guillaume Rousse <address@concealed>]

Le 05/03/2013 17:34, David Verdin a écrit :
[..]
> I propose you put below:
>
> 1- Your code design suggestion
> 2- Your code documentation preferred structure (I think we agreed to use
> pod documentation now, didn't we?)
> 3- Your code presentation preferences (for example, I prefer tabs to
> spaces :-P ).
I fully converted some modules in my branch to tabulation-only 
indentation, such as Sympa::Tools::Bounce. With 5 indentations steps 
(one function, two loops, two conditionals), some code lines start at 
column 41. If you restrain yourself to 78-chars based lines, which is 
still considered a good practice despite everyone having 1600x1200 
graphical display, this leaves less than 50% of text width available...

> We'll compromise aroud this and constitute a set of coding best
> practices to apply from now on.
OK, let's start.

It would be wonderful to have a plugin-based codebase, indeed. But to do 
what ? Or rather, what is the code we should turn into plugins ? And how 
? Because right now, it's quite difficult to figure what are the 
differents parts of Sympa, and where each part starts, and where it ends.

I for instance once imaginated to add Kerberos-authentication support to 
the web interface, but I quickly realized I had first to redesign the 
whole Auth module, just because I was unable to understand its 
interface. Consequently, I was unable to assert which code parts I was 
free to change, and which were used externaly. And it was only a 
specific subsystem, not the whole core...

So my current position is that we should first make the current 
architecture more structured and readable, by local refactoring, before 
jumping into some "let's redesign everything" discussion.

We managed to get some minimal consensus about syntax in a recent 
discussion, but we're far from having it enforced everywhere in current 
code base...

And there is still plenty of work to do to just achieve sane functions 
interfaces and names. Just to name a few:

- Sympa::List::request_auth subroutine can be used either as a function 
or as a method, and tries to act accordingly...

- The whole Sympa::List module mixes OO and non-OO interface into the 
same namespace

- I'm still unable to figure out how Sympa::PlainDigest module works, as 
this kind of invocation is plain chinese for me:
msg->{'plain_body'} = $mail->Sympa::PlainDigest::plain_body_as_string();

- Sympa::Configuration and Sympa::Log are still used directly by most 
modules, making quite difficult to use and test them separatly

- we have some magnificent functions whose name is exactly the opposite 
of what they do, such as 'Sympa::Log::set_daemon' than just convert its 
input into something else and returns it...

Look what I've done for instance with Sympa::Tools::Bounce and 
Sympa::Tools::SMIME. I normalized function names and arguments lists, 
and made a clear distinction between private and public functions, and 
isolated them from Sympa::Configuration dependency. And I added test 
suites for each of them. Now they are fully 
modularisable/externalisable/whatever, because their limits are 
basically defined.

So my answer to Marc's proposal would be:
1) do not waste too much time right now discuting global architecture, I 
don't have enough understanding myself
2) finish to write current consensus (I'm volonteer for it)
3) finish to enforce it everywhere
4) enlarge this consensus progressively, once easy issues such as syntax 
have been dealt with. For instance, we had a discussion about error 
management some times ago, without much result AFAIR.

Let's try some hazardous food-based metaphor: before trying to turn the 
whole plate of spaghetti we have now into something better, let's first 
convert it to a dinner table, where the appetizers, the starter, the 
main course and the desert are clearly separated and distinguishable 
from each others.

About my own personal coding style preferences, most of them are
summarized in the Perl Best Practices book, from Damian Conway 
(http://shop.oreilly.com/product/9780596001735.do) which is generally 
considered a reference in the Perl community.
--
Guillaume Rousse
INRIA, Direction des systèmes d'information
Domaine de Voluceau
Rocquencourt - BP 105
78153 Le Chesnay
Tel: 01 39 63 58 31

Attachment: smime.p7s
Description: Signature cryptographique S/MIME