This document attempts to explaing the guide line of naming rules of preferences and accessing them.
This document is still under discussion.
By convention, preference names are period separated. Preferences for a feature are grouped together with a common prefix. For example:
foo.bar.enabled foo.bar.baz_range.min foo.bar.baz_range.max
If code may want to observe preference changes for a group of preferences, they should be grouped together with a common prefix to improve observer performane.
Preferences which enable or disable a feature should be named <root>.featurename.enabled with a boolean type. If an
"enabled" pref does not always enable or disable the feature, you may need to add another pref which enables or disables the feature forcibly (i.e., ignoring the condition). The pref name should be
Preference names should be easy to understand. It's better to use a long name such as
"use_it_only_when_it_is_available" than a cryptic name which might cause confusion.
When to use preferences
Prefs may/should be used in the following situations:
- To store a user-visible preference setting. Preferences of this type require UX review.
- To enable release drivers to turn a feature off easily if there is a problem found during the release process. Once a feature has shipped, this preference type should probably be removed.
- To control features which are experimental or not ready to ship to our release users. Per-channel defaults control which experimental features are enabled for each prerelease population.
- Other internal usage: for example to facilitate A/B testing via telemetry experiments, or to control automated test behavior. In these cases consider whether it would be better to use a runtime setting instead of a persistent preference to control the behavior.
Preferences should not be used to expose features to power users via about:config settings. In order to make support better, it is far better for these users to install an addon to change the default behavior, even if the addon simply changes a runtime flag. This allows us to see non-default settings in about:support, Firefox Health Report, and crash-stats, and they are properly disabled when running in Firefox safe mode.
How to add new preference
If a preference is used by core platform/Gecko code, a default value should normally be added to
modules/libpref/src/init/all.js. This default is shared all Mozilla products such as Firefox, Thunderbird, Firefox for Android and Firefox OS. If you need to set different initial value for specific product, you can use
If a preference is used only by application-specific code, the default should live in the relevant app-specific default file.
Guidelines of getting preference in C++ code
When you're hacking internal code of libxul, you can use API defined in
If you need to get a preference value at very hot path, you shouldn't use
Preferences::Get*(). Instead of that there are two kinds of API sets.
Preferences::Add*VarCache(). This API modifies registed static variable to the latest preference value automatically. Therefore, this is very useful if you don't need to reinitialize someting when the pref is changed.
The other is
Preferences::RegisterCallback(). You can register a call back method for preferences which you want to observe the changes. If you use this, you need to call
Preferences::UnregisterCallback() when you don't need it anymore. If you need a whole time while our process is running, you should call it at shutting down XPCOM. Most modules have an observer of XPCOM shudown and calls
Shutdown() method of a lot of classes. See
layout/build/nsLayoutStatics.cpp) for the example.
The prerefences system doesn't support float types natively. One workaround is to use integer preference whose value is mutilplied by 10, 100 or 1000. You should explain the value meaning in
modules/libpref/src/init/all.js if you define its initial value. The other is to use string preference and convert to float using