Developers of Sympa

[David Verdin <address@concealed>]

Hi, smee again,

Le 07/03/13 17:02, Guillaume Rousse a écrit :

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.

Exactly the questions I want to answer.
I am perfectly happy with how you deal now with the deintrication of our code. I fully agree with you: the most important thing is to increase code clarity and maintainability.

More below.

address@concealed">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.

The plugin thingy is more of a long-term plan. Actually, all this discussion arose because Mark (not Marc Chantreux, Mark Overmeer) had to dig in our code to develop a new functionnality and made then a lot of suggestions. What we did not understand at first was that he wanted us to accept these suggetions as new paradigms in Sympa to eases his developements; We had to explain him that we were not there yet. We explained about all the work we did recently to improve the code design. And also that, as we are now five people involved in Sympa, I want developpers to express about our code design preferences and not accept the first suggestion as a new paradigm and then enforce it. Hence my mail.

I think that we could probably find coding rules (enforce object orientation, for example) but certainly not now. Probably for the next version.

I thought that, over the cours of next year we could work on code architecture until summer is over, and then work on new features using this new architecture.
We could keep going this way for each version: first, we improve code design, then we use this code design to develop new features. Half / half, roughly.

But for this, we need to know where we want to go.

address@concealed">

address@concealed">
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.

Yes, That's the kind of issues we need to address right now.

address@concealed">
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

That's the answer I gave him: "Your ideas are interesting, but now is not the time to apply them; We don't even know whether they are the good choice."

address@concealed">2) finish to write current consensus (I'm volonteer for it)

As far as I see, for now, we compromised on the followings:

Documentation:

=head1 CATEGORY

with section being either FUNCTIONS, CLASS METHODS or INSTANCE METHODS

=head2 prototype

with prototype being:
- foo($var1, $var2, ...) for a function
- Class->foo($var1, $var2, ...) for a class method
- $object->foo($var1, $var2, ...) for an instance method

Description.

A plain english sentence.

=head3 Parameters

=over

=item * I<$var1>: purpose, nature

=back

=head3 Return value

A plain english sentence.

Code:

• Move from new Object(...) to Object->new(...)
• Get rid of ampersands (&) at the start of subs,
• use perltidy. Soji suggested the following .perltidyrc:

---------- >8 ---------------- >8 ---------------- >8 ----------
-bar   # Opening brace always on right (* no)
-bbt=1 # Medium block brace tightness
-bt=2  # Medium brace tightness (* 1)
-ce    # Cuddled else (* no)
-ci=4  # Continuation indent is 4 cols
-cti=0 # No extra indentation for closing brackets
-et=8  # Entab leading 8 whitespace (* none)
-i=4   # Indent level is 4 cols
-l=78  # Max line witdh is 78 cols
-nolq  # Don't outdent long quoted strings
-nsbl  # No opening sub brace on new line (* -sbl)
-nsfs  # No space before semicolons
-pt=2  # Medium parenthesis tightness (* 1)
-sbt=2 # Medium square bracket tightness (* 1)
-se    # Errors to STDERR
#-st   # Output to STDOUT
-vt=2  # Maximal vertical tightness
-wba="% + - * / x != == >= <= =~ !~ < > | & >= < = **= += *= &= <<= &&= -= /= |= >>= ||= .= %= ^= x= || && . ? : and or xor"
# Break after all operators (* not contains "||" and tokens appear after it)
---------- 8< ---------------- 8< ---------------- 8< ----------

This lead to a mix of tabs and spaces which also a bad mixture on my opinion.
I also disagree with the max line width of 78 columns. Most modern editors - even vi - are able to ad new lines if a line is too long. What is the rationale behind the 78 columns limit?

All the rest is fine to me. Once we're OK with the pertlidy formatting, we can had an automatic perltidy execution somewhere (as a post-commit hook, for example).


anf inally, generally speaking, we want to have clear modules with distinct usages, that can be independently tested and used, by I don't see any way to formally phrase it.

address@concealed">3) finish to enforce it everywhere

With an iron fist if necessary.

address@concealed">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.

Indeed. To sum up my tohoughts: I don't want Sympa to die, but I want errors to be cascaded from the point where the error occurs to the point where tha calls started.

address@concealed">
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.

And don't forget: once the table is set, let's all have a good beer together!
June in Montpelleir would probably be the good time and place for this...

address@concealed">
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.

I ordered it...

Thanks for your input, Guillaume.

Best regards,

David

address@concealed">

--

A bug in Sympa? Quick! To the bug tracker!

David Verdin GIP RENATER - Direction Technique Service applicatifs aux utilisateurs Tél : +33 2 23 23 69 71

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