Guidelines for naming preferences?

[Masayuki Nakano]

Hi, folks.

I'm looking for guidelines for naming preferences. However, I've never
found it yet. I guess that there is no guidelines.

If so, I'd like somebody to create a common guidelines in MDN.



When I work on some bugs, I need to add a new option for a pref
switchable behavior, e.g., if we need to add a new option to a feature
and the new one isn't enabled in default settings, it's better to add
new pref for the additional option in some cases.

I sometimes have trouble about naming a new pref in such situation.

A lot of prefs which just switches a feature disabled or enabled are:

> |foo.a_feature_name|

Then, new pref becomes like:

> |foo.a_feature_name.option|

I feel that this is not good especially following case:

> |foo.a_feature_name|
> |foo.a_feature_name.disabled_on_some_environments|

I think that a pref which enables/disables a feature should end with
|.enabled|. Then, above example becomes:

> |foo.a_feature_name.enabled|
> |foo.a_feature_name.disabled_on_some_environments|

The can be defined by a formula:

<general-group>.(<sub-group>.)*<target-feature>.<state>

The <state> shouldn't be omitted.

And also, <sub-group> should be used as far as possible.

For example, some metrics/colors which can be retrieved with LookAndFeel
class can be override by hidden prefs. The most hidden prefs are named
as |ui.<metricsName>| or |ui.<colorName>|.
http://mxr.mozilla.org/mozilla-central/source/widget/xpwidgets/nsXPLookAndFeel.cpp#26

This causes a trouble.

nsXPLookAndFeel observes every pref. For doing that, it observes *all*
prefs under |ui.|.
http://mxr.mozilla.org/mozilla-central/source/widget/xpwidgets/nsXPLookAndFeel.cpp#430

And the observer uses 3 loops for retrieving the pref cache from the arrays.
http://mxr.mozilla.org/mozilla-central/source/widget/xpwidgets/nsXPLookAndFeel.cpp#388

If somebody changes a pref under |ui.| at runtime, every change causes
running this expensive method.

So, I think that they should be named as:

> ui.system_metrics.int.<metricsName>
> ui.system_metrics.float.<metricsName>
> ui.system_color.<colorName>

Then, observer never harms performance of other modules.


For preventing these unfortunate things, we should define good
guidelines about pref names.


# Anyway, if it's allowed, we should rename the pref names referred from
nxXPLookAndFeel even though customized users will need to set them again.

Thanks in advance.

--
Masayuki Nakano <masa...@d-toybox.com>
Manager, Internationalization, Mozilla Japan.

[Benjamin Smedberg]

On 6/19/2014 10:00 PM, Masayuki Nakano wrote:
> I'm looking for guidelines for naming preferences. However, I've never
> found it yet. I guess that there is no guidelines.

That is correct. The current rule is to use common sense and coordinate
with the module owner.

If the pref will be exposed in the UI preferences, you should also
coordinate with UX design to make sure that we can express the
preference in the UI in a useful way.

> When I work on some bugs, I need to add a new option for a pref
> switchable behavior, e.g., if we need to add a new option to a feature
> and the new one isn't enabled in default settings, it's better to add
> new pref for the additional option in some cases.

Here are the reasons we should be adding prefs:

A. We actually want to expose the option in the preference UI (needs UX
review)
B. To enable release drivers to turn it off easily if there is a problem
found
C. a feature is experimental and we want to limit it to certain channels
while it is stabilized
D. To enable other internal usage: e.g. A/B testing via telemetry
experiments

I believe that we should not be adding hidden prefs just because a small
minority of people might want a feature, but we've decided not to expose
it in the browser preferences. Those kinds of choices should be made by
installing Firefox extensions. In particular, using an extension instead
of a hidden pref setting means that we will see the non-default choice
in various metrics like about:support, telemetry/FHR, and that Firefox
safe mode reverts the setting in case of problems.

In any case, this probably doesn't have much to do with naming ;-)

> I think that a pref which enables/disables a feature should end with
> |.enabled|. Then, above example becomes:
>
> > |foo.a_feature_name.enabled|
> > |foo.a_feature_name.disabled_on_some_environments|

If it's a boolean feature, I think the common pattern is to used
foo.feature.enabled. e.g. app.update.enabled or dom.ipc.plugins.enabled.

This sounds reasonable to document.

>
> The can be defined by a formula:
>
> <general-group>.(<sub-group>.)*<target-feature>.<state>
>
> The <state> shouldn't be omitted.

I think this rule is too general. Let's stick with the "enabled" rule
for now.

>
> And also, <sub-group> should be used as far as possible.

Why? Flat names seem quite reasonable.

>
> nsXPLookAndFeel observes every pref. For doing that, it observes *all*
> prefs under |ui.|.
> http://mxr.mozilla.org/mozilla-central/source/widget/xpwidgets/nsXPLookAndFeel.cpp#430
>
>
> And the observer uses 3 loops for retrieving the pref cache from the
> arrays.
> http://mxr.mozilla.org/mozilla-central/source/widget/xpwidgets/nsXPLookAndFeel.cpp#388
>
>
> If somebody changes a pref under |ui.| at runtime, every change causes
> running this expensive method.

How expensive? Pref changes at runtime are in quite unusual after
startup, and I don't think we should necessarily optimize for this case.

On the other hand, I do think it makes sense to consider the
implementation when defining a pref namespace: if you're observing an
overly broad branch and there's an easy way to design that away, that
sounds reasonable.

>
> For example, some metrics/colors which can be retrieved with
> LookAndFeel class can be override by hidden prefs. The most hidden
> prefs are named as |ui.<metricsName>| or |ui.<colorName>|.
> http://mxr.mozilla.org/mozilla-central/source/widget/xpwidgets/nsXPLookAndFeel.cpp#26
>

> # Anyway, if it's allowed, we should rename the pref names referred
> from nxXPLookAndFeel even though customized users will need to set
> them again.

Do we need this code at all? This sounds like the kind of code that
would be better to remove entirely.

--BDS

[Masayuki Nakano]

Thank you for the reply, but sorry for the delay.

On 2014/06/20 23:25, Benjamin Smedberg wrote:
> On 6/19/2014 10:00 PM, Masayuki Nakano wrote:
>> When I work on some bugs, I need to add a new option for a pref
>> switchable behavior, e.g., if we need to add a new option to a feature
>> and the new one isn't enabled in default settings, it's better to add
>> new pref for the additional option in some cases.
>
> Here are the reasons we should be adding prefs:
>
> A. We actually want to expose the option in the preference UI (needs UX
> review)
> B. To enable release drivers to turn it off easily if there is a problem
> found
> C. a feature is experimental and we want to limit it to certain channels
> while it is stabilized
> D. To enable other internal usage: e.g. A/B testing via telemetry
> experiments
>
> I believe that we should not be adding hidden prefs just because a small
> minority of people might want a feature, but we've decided not to expose
> it in the browser preferences. Those kinds of choices should be made by
> installing Firefox extensions. In particular, using an extension instead
> of a hidden pref setting means that we will see the non-default choice
> in various metrics like about:support, telemetry/FHR, and that Firefox
> safe mode reverts the setting in case of problems.
>
> In any case, this probably doesn't have much to do with naming ;-)

There are two hidden prefs.

One is not in UI but shown in the list of about:config. The other is not
in both UI and about:config. I.g., there is a checking the pref value
code but not included in all.js and other similar files.

I think that the former is important for some minority users. Yes, they
must be minority but their reason to use Firefox must be the
customizability by this kind of hidden prefs. And such minority users
who can customize about:config may help their friends and family to use
our product. Therefore, I believe this is important for keeping market
share.

The latter should be used for developing or automated tests.

>> And also, <sub-group> should be used as far as possible.
>
> Why? Flat names seem quite reasonable.

The reason is for the runtime cost of observing brunches as I mentioned
below.

>> nsXPLookAndFeel observes every pref. For doing that, it observes *all*
>> prefs under |ui.|.
>> http://mxr.mozilla.org/mozilla-central/source/widget/xpwidgets/nsXPLookAndFeel.cpp#430
>>
>>
>> And the observer uses 3 loops for retrieving the pref cache from the
>> arrays.
>> http://mxr.mozilla.org/mozilla-central/source/widget/xpwidgets/nsXPLookAndFeel.cpp#388
>>
>>
>> If somebody changes a pref under |ui.| at runtime, every change causes
>> running this expensive method.
>
> How expensive? Pref changes at runtime are in quite unusual after
> startup, and I don't think we should necessarily optimize for this case.

Although, I don't measure it actually. But if somebody adds a pref under
|ui.| and it may be updated from UI, it may cause short hangup at
changing it. This is really bad UX and automated tests must not be able
to detect this problem.

>> For example, some metrics/colors which can be retrieved with
>> LookAndFeel class can be override by hidden prefs. The most hidden
>> prefs are named as |ui.<metricsName>| or |ui.<colorName>|.
>> http://mxr.mozilla.org/mozilla-central/source/widget/xpwidgets/nsXPLookAndFeel.cpp#26
>>
>> # Anyway, if it's allowed, we should rename the pref names referred
>> from nxXPLookAndFeel even though customized users will need to set
>> them again.
>
> Do we need this code at all? This sounds like the kind of code that
> would be better to remove entirely.

At least I really need this because these prefs can emulate other
environments on each environment. E.g., on Windows, we can test Mac OS X
style scrollbar. This is very important to work on around XUL.

# FYI: These prefs are not listed in about:config.

[Masayuki Nakano]

Hi, I wrote a draft of the guideline in MDN roughly.

I hope a lot of developers discuss the rules and improve this draft!

Thanks in advance.

[Masayuki Nakano]

On 2014/06/30 22:51, Masayuki Nakano wrote:
> Hi, I wrote a draft of the guideline in MDN roughly.
>
> I hope a lot of developers discuss the rules and improve this draft!

Oops, the draft is here. Sorry for the spam.
https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Preferences

[Gavin Sharp]

On Mon, Jun 30, 2014 at 12:24 AM, Masayuki Nakano <masa...@d-toybox.com> wrote:
> One is not in UI but shown in the list of about:config. The other is not in
> both UI and about:config. I.g., there is a checking the pref value code but
> not included in all.js and other similar files.
>
> I think that the former is important for some minority users. Yes, they must
> be minority but their reason to use Firefox must be the customizability by
> this kind of hidden prefs. And such minority users who can customize
> about:config may help their friends and family to use our product.
> Therefore, I believe this is important for keeping market share.

I disagree pretty strongly. There's always a judgement call involved,
and it's possible for some cases to be exceptional, but as a general
guideline we shouldn't be adding prefs to about:config "for power
users", because the long-term costs to adding them has shown to be
quite significant even in seemingly trivial cases. As Benjamin notes,
an add-on is a much better way to suggest people customize these
things, and writing an add-on that sets a pref is trivial.

Gavin

[Benjamin Smedberg]

On 6/30/2014 9:53 AM, Masayuki Nakano wrote:
> On 2014/06/30 22:51, Masayuki Nakano wrote:
>> Hi, I wrote a draft of the guideline in MDN roughly.
>>
>> I hope a lot of developers discuss the rules and improve this draft!
>
> Oops, the draft is here. Sorry for the spam.
> https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Preferences
>

Thanks for starting this. I've made some significant modifications:

* Added a list of situations where prefs should or shouldn't be used
* Removed the list of toplevel pref "roots". I don't think this list is
valuable, and I don't think that adding new roots is necessarily bad.
* I don't believe there's a good case for preferences that are read but
don't appear in the default pref files. I have changed the
recommendation to always add a default value
* Clarified where default prefs belong: prefs that are read by gecko
belong in all.js, but Firefox-specific prefs belong in firefox.js

--BDS

[Gavin Sharp]

On Fri, Jun 20, 2014 at 7:25 AM, Benjamin Smedberg
<benj...@smedbergs.us> wrote:
> I believe that we should not be adding hidden prefs just because a small
> minority of people might want a feature, but we've decided not to expose it
> in the browser preferences. Those kinds of choices should be made by
> installing Firefox extensions.

If we're going to be suggesting people write add-ons to flip run-time
switches not via prefs, it'd be nice to actually separate the
"run-time switch API" aspect of prefs into a separate API that's not
designed to be persistent. It would make the "write an add-on"
solution to adjusting behavior at run time require less knowledge of
the specifics of the feature.

Gavin