Mailing-List: contact dev-help@directory.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Apache Directory Developers List" <dev@directory.apache.org>
Received-SPF: pass (athena.apache.org: domain of elecharny@gmail.com
 designates 66.249.82.237 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=beta;
        h=received:message-id:date:from:reply-to:to:subject:in-reply-to:mime-version:content-type:content-transfer-encoding:content-disposition:references;
        b=jam9CcTZrMmNWkl5CpINloO6DonWyvjCcyMbCcBRNIZIPkxCDUlIM+Tpp/l4qWz0n1P8TS8SWDLgnSPMxrNA5BbK5N83aSKIZnZ1d8QMTxwSIswXyS4v+u2RAxgKl3rSuhVLs0qSwZWqBwf+lekRJirzYsQ31QrM2Ch9ZmlSpE8=
Message-ID: <d45b08f00708172230x457f417eu36361cc705f11fab@mail.gmail.com>
Date: Sat, 18 Aug 2007 07:30:55 +0200
From: "Emmanuel Lecharny" <elecharny@gmail.com>
Reply-To: elecharny@iktek.com
To: "Apache Directory Developers List" <dev@directory.apache.org>
Subject: Re: Pattern usage and writing self documenting code
In-Reply-To: <a32f6b020708171923r778bc708qb8b59c7fc4b07a22@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline
References: <a32f6b020708171923r778bc708qb8b59c7fc4b07a22@mail.gmail.com>

Hi ALex,

I can understand your position, and furthermore, you know how I hate
patterns because they are conveying some kind of semantic which is
often over abused. I know a lot of people who are coding using
patterns everywhere thinking that patterns is a good substitute for
design. Now, people often confuse patterns and GoF, thinking that
there are no other patterns thet the ones described in this Sacred
Book.

Pattern are good to use if they are commonly used by a group of
people, and understood. Otherwise, they are always cryptic, and
whatever self-documentation you add, you will end by browsing the
internet crazy finding a zillion of different explanations about what
is the offending pattern all about. I see patterns as a good
justification for people who don't want to think, when they are
abused...

Patterns are by no mean the solution to every programming problem,
they should be used in clearly identified cases.

In this very special case, what was done is to cretae a separation
between the action and the transport. Action will remain the same,
whatever the used transport. Of course, this will clutter the initial
code, as we have added this transport layer, when the initial code was
just about writing a locally active tool (you were just able to use
the tools on the same machine than the server). Now, the idea is to
able someone using a tool like Apache Directory Studio to do the same
thing, possibly communicating with the server using a HTTP transport.
I won't call it J2ee-ish, but MVC-ish, which is not by far a bad
pattern ...

At the end, yes, this is far more complex than the previous code. But
everything has a price, and you can just think that enter in a code
which is complex will be at no price. The choice here is between
simplistic and limitated code, or more complex but potentially more
powerful code. I don't think we over abused patterns in this very
case, but of course this can be discussed.

I understand that we can have different visions of how should be
written a piece of code, but trust me, this one has been seriously
discussed before being implemented, and as I didn't implemented it nor
choose the implementation, I'm more confident to defend it than if I
was the author. There might be room for improvement, for sure (names
used may not be perfect), but I really think that the used pattern
(proxy) is the correct one for this very case.

let's wait for pam to be back from hollidays to further this
discussion, he is the one who is the best to explain what has been
done !

Thanks for your comment anyways, Alex, I'm sure we will find a better
way to code this part when all the elements will be put on the table !

Emmanuel

On 8/18/07, Alex Karasulu <akarasulu@apache.org> wrote:
> Hi all,
>
> While processing the JIRA I noticed an issue that I had fixed in ADS 1.0 =
but
> did not merge
> into the trunk for ADS 1.5.  I am referring to the following JIRA issue
> here:
>
>     https://issues.apache.org/jira/browse/DIRSERVER-922
>
> I remember distinctly trying to merge these changes to the trunk after
> implementing the fix in the 1.0
> branch however it was impossible to merge because the apacheds-tools proj=
ect
> was completely
> refactored with a new design.  While looking at that code I could not eas=
ily
> understand it.
> After the fact though someone pointed me to some documentation on the
> redesign that took place.
> It would have been nice to have this link at that point when I had to do =
the
> merge but this is not
> always possible.  Hence my point as to why writing self documenting code =
is
> critical.
>
> The redesign added a bunch of patterns with unclear names which was
> confusing to me.
> Besides being somewhat J2EE-ish (which I don't like) the patterns were
> somewhat off. I could
> not get familiar enough with it in a reasonable amount of time to fix the
> conflicts I encountered
> on the merge. Again I encountered this issue in JIRA and the same problem=
 is
> still there so I
> re-assigned the issue to who SVN reported as the redesigner.
>
> My point to all this is that we must chose names properly for elements in
> patterns and
> make sure we use patterns properly instead of tweaking them to the point =
of
> no recognition.
> Is'nt conveying design through instant recognition the point to using
> patterns in the first
> place.  There is no point to using patterns unless you abide by them.
> Furthermore it's
> not just enough to write documentation on your design or redesign if the
> names are funky
> and the patterns are warped to force a fit.  This is actually a worse
> practice.  If you don't
> try to force the pattern then pattern names would not be mixed with clear
> names
> for the classes used.  Mixing them and changing the pattern to suite is
> creating more
> confusion while removing the effectiveness of using the pattern in the fi=
rst
> place.
>
> I'm seeing this practice repeatedly and it's starting to consume more of =
my
> time and
> is causing me to take actions that I don't like: for example I just pushe=
d
> this JIRA issue
> above to PAM instead of stepping up to the plate and fixing it myself.  T=
his
> is all
> because groking this redesign in the time alotted was impossible for me.
> This practice
> is making the code unfamiliar to those who were capable before of navigat=
ing
> it.
>
> This criticism is intended to be constructive so please don't anyone take=
 it
> personally.
> This is a problem that I have been noticing and dealing with in various
> places.  This
> particular example above is just one of those instances.   I myself have
> made this mistake
> all too often and others have grok'd through my cryptic code so I have to
> take my own
> advice.  I just want to speak up since our projects are getting more comp=
lex
> every day.
>
> Alex
>
>


--=20
Regards,
Cordialement,
Emmanuel L=E9charny
www.iktek.com