This document attempts to explaining the guide line of naming rules of preferences and accessing them.

This document is still under discussion.

Naming guidelines

By convention, preference names are period separated. Preferences for a feature are grouped together with a common prefix. For example:

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 performance.

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 "force_disable" or "force_enable".

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 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/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 browser/app/profile/firefox.js, mailnews/mailnews.js, mobile/android/app/mobile.js and/or b2g/app/b2g.js.

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 modules/libpref/public/Preferences.h.

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.

One is Preferences::Add*VarCache(). This API modifies registered static variable to the latest preference value automatically. Therefore, this is very useful if you don't need to reinitialize something 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 shutdown and calls Shutdown() method of a lot of classes. See nsLayoutStatics::Shutdown() (layout/build/nsLayoutStatics.cpp) for the example.

Float values

The preferences system doesn't support float types natively. One workaround is to use integer preference whose value is multiplied 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 parseFloat (JavaScript) or atof (C++).