Namespaces are a powerful organisational tool for APIs. To give an
example from my own work on the new-portal package, it currently has a
single namespace "portal::". But portal is fairly complex, with a
number of distinct "objects": portals, portal elements (html boxes on
a portal), portal datasources (the stuff that fills a portal element),
portal layouts (like 1 column or 2 column), and portal themes (a style
of decoration). With one flat namespace, or the old style of having no
namespace at all, the multitude of procs makes for a mess of
code. Also, It doesn't help matters that all the procs are in one huge
file. So, just as splitting up this moby tcl file into smaller object
specific files is a boon to comprehension and maintainability, so is
splitting up the namespace into subnamespaces like portal::element::
and portal::datasource::
That's for new code, but what about old ad_* code? Here there are
some facts about the old code:
1. many procs we inherited from ad_ are badly designed, named, and/or
organised and, not to mention, rather buggy.
2. namespaces are widely used in the old code. A quick grep through
the tree for "namespace eval" will show dozens of uses of namespaces
from aD'ers. Notably, both acs-templating and cms use subnamespaces
extensively.
Parts of the core ad_* api need to be refactored and fixed if oacs
is to improve as a toolkit. I doubt there is much debate there.
If done with care, fixing parts of core that are badly needing repair
using new namespace procs will:
1. NOT break old code that relies on an old ad_foo proc. the ad_foo
proc will work just as if no code was added (with probably with less
bugs)
2. NOT "replace" or "remove" the ad_foo proc until developers have had
enough time to become familiar with the new namespaced procs and
proper warnings have been issued to everyone.
There are two things wrong with what you call a "trivial renaming of
ad_parameter". A cursory glance at the code will show that: First, the
work done on the parameter namespace was not trivial. It was an
thoughtful cleaning and refactoring, adding such improvements as the
exclusive use of named parameters. It's more orthogonal and
explicit. Easier for newbies and old hands alike. Second, what one
intuitively thinks of with "renaming", i.e. a removal of the old proc,
_did not happen_. ad_parameter is still there functioning exactly as
before. Developers can use it without even knowing that the
parameter:: namespace exists.
With this amount of care given to adding cleaner, less buggy, and
easier to understand namespaced code in the core, a core which is
_already_ a mix of ad_ and namespaced procs, namespaces are a win,
for old and new code alike.
