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:
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.