GNOME Shell Style Guide

Gjs Style Guide

We defer most of our style guidelines to the ones in the Gjs Style Guide, so be sure to read it before developing the JavaScript code for GNOME Shell.

Imports

List external imports first, then list internal imports. Keep both sets in the alphabetical order and separate them by a blank line.

Imports of GNOME Shell C modules, such as imports.gi.Shell should be in the external imports set. This includes imports of modules that were copied from other projects, such as imports.gi.Big and imports.gi.Meta.

Only imports of the local GNOME Shell JavaScript modules should be in the internal imports set.

  // Sample list of imports
  const Big = imports.gi.Big;
  const Clutter = imports.gi.Clutter;
  const Gtk = imports.gi.Gtk;
  const Lang = imports.lang;
  const Shell = imports.gi.Shell;
  
  const Main = imports.ui.main;
  const Overlay = imports.ui.overlay;
  const Panel = imports.ui.panel;

Methods

Place class methods into separate sections headed by the method type and maintained in the following order:

  //// Public methods ////
  //// Protected methods ////
  //// Pure virtual protected methods ////
  //// Private methods ////

Have a comment on top of each method describing what the method does. Describe the return value if the method has one. There is no need to explicitly describe each argument if the method description makes it obvious what they are.

Protected Methods and Variables

Protected methods and variables, as well as private ones, should begin with an underscore.

Strings

Use single quotes (e.g. 'foo') for untranslated strings/constants, and double quotes (e.g. "foo") for strings that should be translated. (gettext doesn't understand javascript, so it treats it as C, so you must use double-quotes on translated strings, or they won't get picked up into the .po files.)

Wrapper Classes

When creating a javascript wrapper for a ClutterActor:

• Store a pointer from the wrapper to the actor in this.actor

• Store a back-pointer from the actor to the wrapper in this.actor._delegate, if useful. (This is used by the drag-and-drop code, for instance, to find an acceptDrop() method for an actor.

• Connect to the actor's destroy signal and perform cleanup there; don't assume that the actor will only be destroyed via codepaths in the wrapper. The wrapper may have a destroy() method of its own, but if so, it should just call this.actor.destroy();