[Phpgroupware-developers] Think Forward Compatible

[Miles Lott]

Since this is a special group, let me preface by saying that this is an
editorial.  Its scope is general, and not specific to this group. 
Assuming it connects on some plane with reality, no matter how
tangentially, then it was worth the 20 minutes it took to write it. 
Some of you may read my code and start ba-ing like sheep when you go
back to read this.  Please send audio recordings if this happens...

        There is a lot of talk, and indeed a lot of effort, that strives toward
writing code that is backward-compatible.  With each new release of a
package, with each addition of a new feature, coders typically go out of
their way to make sure they don't break the program in its common use. 
At least we users expect it.

        What seems to be lost on some folks, from the megaconglomerates down to
the free individual, is the fundamental value of writing code that is at
once functional, readable, and expandable.  True, people have talked for
years about object-oriented code and environments and such.  Still
others are purveyors of the reuseable code or building block concept. 
Even fewer are particular about code formatting and inline or outbound
(ANY!) documentation.

        What I would like to see is more code that is written to be what I will
call forward-compatible.  You see, if one person or maybe even two are
the only ones to ever work on and understand the code they write, then
perhaps it is enough that they get the job done.  Hopefully, they write
nice, clean, secure code.  And, with any luck, their user base is such
that readability and expandability is never an issue.  If they are the
extent of their userbase, then I guess we won't be invited to critique
it anyway.

        So just what do I mean by 'forward-compatible'?  It is really quite
simple, but I thought it needed to be said.  Read the following with the
assumption that number 0 is 'write functional (and secure) code':

1. Write code that is formatted so it can be read by someone besides
you.  This is not only a formatting issue, but a self-documentation
issue.  You mean to tell me that only lawyers know how to outline?  Your
code reads like a doctor's signature, my friend.

2. Write code that is organized such that it may be understood by
someone other than yourself.  Yes, you not only have to speak to your
compiler, but you should also be interested in the poor shmuck who later
dives in to fix what you broke, or wants to experiment because they do
not understand that this section is actually perfect.  That poor shmuck
could be you, post-bender.

3. Write code that contains some documentation beyond 'TODO' and 'this
is really ugly'. /* note to self - expound upon that */

4. Don't write a routine to draw three corners of a four corner world
and another to catch the fourth corner, when fashioning and executing a
single two-corner function twice will do.  What, were you educated
stupid?

5. Don't duplicate your code where avoidable.  Yes, there are often time
contraints that prohibit timely organization sometimes.  But I would bet
that more often times than not it is done out of laziness most of the
time.  You've all been there at one time or another time.

6. Write your objects with the realization that as functionally correct,
their internals may be overlooked by others.  Should a function called
make_widget() really be checking on the status of gadget X?  Only if
gadgets make_widgets.  That debate will have to continue elsewhere.

        Yes, object-orientation is a fair chunk of what can make good code in
this scenario.  But the objects themselves must be even better organized
in this method.  Don't rely too heavily upon the building blocks until
you are certain the blocks are solid unto themselves.

        Ok, nothing too earth-shattering here.  Nothing that has not been said
before, I reckon.  There is nothing new under the sun, just people who
insist upon building new mouse traps when the old one does the job
adequately.

        Always strive to build the better mouse trap, but believe that it is
better before imposing it upon the rest of us.  Then show us by making
perfectly lovely code.

-- 

Miles Lott - phpGroupWare
http://www.phpgroupware.org