Parameter names - bug 155628

[Jouni Heikniemi]

Shane H. W. Travis wrote:
> Dave asked that I solicit opinions from developers. I cc:'d a lot of people
> when I wrote up my intent to fix this bug, but this is probably a better way
> to get comments.

I wrote some of my comments to the bug, but I'll repost them here to 
join your nasty little conversation :-)

--
Having given this some thought, it looks like params rewrite (bug 46296) 
is going to remove the immediate user-wise effect the param names have. 
However, it is also true that many of the params have a significant 
effect in the code. Striving to clean that up is a worthy aim, and one 
that cannot (or even should not) be easily done with the other patches.

However, changing the names is a considerable headache for customizers. 
We should start this work at the beginning of a new version cycle (after 
2.20 has branched) and try to finish it prior to 2.22 going to rc. That 
said, a single patch would be totally hellish. Also, the changes we make 
here should also be simultaneously used for cleaning up the semantics of 
the parameter names - while some of the issues below may sound cosmetic, 
I don't think we're going to have as good a chance for fixing up these 
cosmetics as we're going to have now if we start adding underscores anyway.

About the variable names: There are multiple inconsistencies in the way 
the params are named. I believe we should work towards unifying some of 
the param naming concepts (and perhaps documenting them in the dev 
guidelines as well)while we're at this. I'm referring to following kinds 
of issues:

- param names should be in lowercase (LDAP_foo are the only exception)

- the feature-enabling booleans could be named more uniformly. Although 
there is a semantic difference between "allow..." and "use...", in 
practice these options often come very close to one another. Perhaps it 
would be cleaner to have a simple naming scheme for these; I suggest 
"enable_xxx". Things like support_watchers and musthavemilestoneonaceppt 
also belong to this group.

- The "require"-params (such as commentonaccept, noresolveonopenblockers 
and stuff) should have the "require_" prefix to make it clear what they 
actually mean.

- Since we're not going to have the pref names user-visible for long, we 
could just as well make them verbose enough to be clear in the code. 
Stuff like "makeproductgroups" should be expanded to 
"automatically_create_product_bug_groups" or whatever (that example
might've exaggerated things a bit, but I believe the idea gets through:
Some of the params have such esoteric names that even the developers 
can't remember their semantics. Although names shouldn't contain 
documentation, they should contain a really good indication of the 
meaning. Another example of the need is "usemenuforusers"... eww.

- Some prefixing to group the properties together would be preferable. 
For example, the authentication related params could be grouped under 
the "auth_" prefix. We already have this for some of the params, but 
LDAP stuff could be prefixed as well. Another candidate would be mail 
related params (mail_ prefix), even though many of them (the template 
related ones) are going away anyway.


All that said, I feel it would be appropriate to first give some thought 
to the generic param naming guidelines, then make this a meta bug and 
start renaming the params in some reasonably sized groups, each of this 
work progressing in a separate bug. That way, if some discussion on a 
certain param's new name rises, it will be contained in a reasonably 
small bug (instead of this becoming a 200+ comment monster á la bug 84876).
--

An aliasing layer is of course a good idea, regardless of whether we 
just go and throw in some underscores or go for a broader renaming session.


As a side note, it's again an interesting situation. There are two 
fundamental mistakes that loom here: One (the one we make every now and 
then) is requiring such perfection that nothing gets done; the other one 
(not usually bothering Bugzilla) is allowing sub-standard solutions to 
pass simply because that's everything offered at the moment. Striking 
the balance between those two requires the ability and desire to 
negotiate, from every person involved. Descending into a flame war 
almost inevitably means ending up at either of the mistakes outlined above.


Jouni