directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Alex Karasulu" <akaras...@apache.org>
Subject Pattern usage and writing self documenting code
Date Sat, 18 Aug 2007 02:23:01 GMT
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 project
was completely
refactored with a new design.  While looking at that code I could not easily
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 first
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 pushed
this JIRA issue
above to PAM instead of stepping up to the plate and fixing it myself.  This
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 navigating
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 complex
every day.

Alex

Mime
View raw message