Internally, elementary uses the following code style guide to ensure that code is consistently formatted both internally and across projects. Consistent and easily-legible code makes it easier for newcomers to learn and contribute. We'd like to recommend that in the spirit of Open Source collaboration, all Vala apps written in the wider ecosystem also follow these guidelines.

Whitespace

White space comes before opening parentheses or braces:

An exception is admitted for Gettext-localized strings, where no space should go between the underscore and the opening parenthese:

Whitespace goes between numbers and operators in all math-related code.

Lines consisting of closing brackets (} or )) should be followed by an empty line, except when followed by another closing bracket or an else statement.

Indentation

Vala

Vala code is indented using 4 spaces for consistency and readability.

In classes, functions, loops and general flow control, the first brace is on the end of the first line ("One True Brace Style"), followed by the indented code, and a line closing the function with a brace:

On conditionals and loops, always use braces even if there's only one line of code:

Cuddled else and else if:

If you are checking the same variable more than twice, use switch/case instead of multiple else/if:

Markup

Markup languages like HTML, XML, and YML should use two-space indentation since they are much more verbose and likely to hit line-length issues sooner.

Classes and Files

A file should only contain one public class.

All files have the same name as the class in them. For example, a file containing the class AbstractAppGrid should be called "AbstractAppGrid.vala"

Classes should be named in a descriptive way, and include the name of any parent classes. For example, a class that subclasses Gtk.ListBoxRow and displays the names of contacts should be called ContactRow.

Comments

Comments are either on the same line as the code they reference or in a special line.

Comments are indented alongside the code, and obvious comments do more harm than good.

Sometimes detailed descriptions in the context of translatable strings are necessary for disambiguation or to help in the creation of accurate translations. For these situations use /// TRANSLATORS: comments.

Variable, Class, and Function Names

Variable and function names are all lower case and separated by underscores:

Classes and enums are Upper Camel Case (aka Pascal Case):

Constants and enum members should be all uppercase and separated by underscores:

The values of constant strings (such as when used with GLib.Action) should be lowercase and separated with dashes:

Casting

Avoid using as keyword when casting as it might give null as result, which could be forgotten to check.

Prefer Properties Over Get/Set Methods

In places or operations where you would otherwise use get or set , you should make use of = instead.

For example, instead of using

you should use

Initialize Objects with Properites

This is especially clearer when initializing an object with many properties. Avoid the following

and instead do this

Create Classes with Properties

This goes for creating methods inside of classes as well. Instead of

you should use

or, where you need some extra logic in the getters and setters:

Preferring properties in classes enables the use of between classes instead of needing to create signals and handle changing properties manually.

Vala Namespaces

Referring to GLib is not necessary. If you want to print something instead of:

You can use

String Formatting

Avoid using literals when formatting strings:

Instead, prefer printf style placeholders:

Warnings in Vala use printf syntax by default:

GTK events

Gtk widgets are intended to respond to click events that can be described as "press + release" instead of "press". Usually it is better to respond to toggle and release events instead of press.

Columns Per Line

Ideally, lines should have no more than 80 characters per line, because this is the default terminal size. However, as an exception, more characters could be added, because most people have wide-enough monitors nowadays. The hard limit is 120 characters.

Splitting Arguments Into Lines

For methods that take multiple arguments, it is not uncommon to have very long line lengths. In this case, treat parenthesis like brackets and split lines at commas like so:

EditorConfig

If you are using elementary Code or your code editor supports , you can use this as a default .editorconfig file in your projects:

When creating a new class, prefer GObject-style construction. This type of class construction separates handling arguments from the main logic of your class. It also ensures that information passed in during construction is still available later, and makes your class more likely to be compatible with GLib's functions like property binding.

A simple class written with GObject-style construction looks like this:

Construction Properties

In the above example, MyClass has a public property foo whose type is int, but we've also declared it as { get; construct; }. This shorthand declares the type of access for this property's get and set functions. Since we declared the property as public, get is also public, but we've declared the set function as construct, which means we can only assign its value as a constructor argument.

We want construction arguments to be public to ensure that we can later get information out of a class that was used to construct it, if need be. But it's important to declare limited set access on properties for future maintainability. Since there is no handling for changes in this property in the construct block, setting this property after the class is constructed would have no effect, even if we allowed it by declaring { get; construct set; }.

Constructors

MyClass also contains a constructor; it describes what arguments are required to construct the class. We've declared here that in order to construct MyClass, we need an int passed in when we initialize a new object such as with var new_class = new MyClass (5);

Inside the constructor, we have a special Object () call, in which we specify a property and its value, Object (foo: foo);. This sets the value of the integer property foo defined earlier to the value received as an argument. It is equivalent to saying this.foo = foo;.

The Construct Block

When using GObject-style construction, a constructor should only contain code that parses arguments and sets property values with the Object () call. All other class construction logic happens in the construct block. Code in the construct block runs every time an instance of this object is created, regardless of the constructor used.

Declaring Multiple Constructors

To see how this style of class construction scales and keeps code organized, let's look at a more complex example. Say we want to display a list of devices. Each device lives in its own row, which is denoted by the class Row. In this example, sometimes we have access to a Device object which stores the name and icon properties of the device, but for some devices we have to pass in those properties manually to construct our row. We can achieve this by declaring two constructors:

• a default constructor that takes two arguments: string name and Icon icon

• a separate, named constructor which takes one argument: a Device object

Note that in both cases, we handle the arguments in the constructor, while the actual logic of creating UI widgets lives in the common construct block.

This way, we can have multiple constructors without having to repeat the initialization logic.

See also