Skip to content

Guide on code style

Jump to bottom
Robert San edited this page Sep 5, 2017 · 5 revisions

Code Style

The purpose of this guide is to provide clean and accurate instructions on writing good code across all elementary projects. This guideline is to be followed on every file, in order to keep our code consistent and readable. We are also inheriting some of the GNOME's Vala guidelines to keep our code consistent with other Vala programs.

If the guidelines here proposed are followed, newcomers to elementary development will be more easily able to join the development and understand code. Besides, it'll make it easier for all developers to work on applications that they don't usually work on, because the code will be consistent. Finally, as Guido Van Rossum said - "Code is much more often read than written", so having nicely written code is crucial.

Whitespace

There is no trailing whitespace at the end of a line, whether it's empty or not. There is also no empty line after declaring a function:

public string get_text () {
    string text = search_entry.get_text ();
    return text;
}

White space comes before opening parentheses:

public string get_text () {}
if (a == 5) return 4;
for (i = 0; i < maximum; i++) {}
my_function_name ();
Object my_instance = new Object ();

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

c = n * 2 + 4;

Indentation

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

In classes, functions, loops and general flow control, the first parentheses 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 curly bracket:

public int my_function (int a, string b, long c, int d, int e) {
    if (a == 5) {
       b = 3;
       c += 2;
       return d;
   }

    return e;
}

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

if (my_var > 2) {
   print ("hello\n");
}

Cuddled else and else if:

if (a == 4) {
    b = 1;
    print ("Yay");
} else if (a == 3) {
    b = 3;
    print ("Not so good");
}

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

switch (week_day) {
   case "Monday":
       message ("Let's work!");
       break;
   case "Tuesday":
   case "Wednesday":
       message ("What about watching a movie?");
       break;
   default:
       message ("You don't have any recommendation.");
       break;
}
``

## Classes and files

Only having one class per file is recommended.

All files have the same name of the class in them.

Separate code into classes for easier extensibility.

## Comments

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

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

```vala
/* User chose number five */
if (a == 5) {
   B = 4;           // Update value of b
   c = 0;           // No need for c to be positive
   l = n * 2 + 4;   // Clear l variable
}

Variable names, class names, function names

my_variable = 5;     // Variable names
MyClass              // Class names
my_function_name (); // Type/Function/Method names
MY_C     // Constants are all caps with underscores

/* For enum members, all uppercase and underscores */
enum OperatingSystem { // An enum name is the same as ClassesNames
    UBUNTU,
    ELEMENTARY_OS,
    VERY_LONG_OS_NAME
}

Also worth referring that there should be no Hungarian notation, and no mix of any kinds of notations.

Casting

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

/* OK */
((Gtk.Entry) widget).max_width_chars

/* NOT OK as this approach requires a check for null */
 (widget as Gtk.Entry).max_width_chars
 Use of '=' in place of 'set'

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

For example, instead of using

set_can_focus (false);

you should use

can_focus = false;

Vala namespaces

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

GLib.print ("Hello World");
print ("Hello World");

Opt for the second one, it's much cleaner.

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.

GPL Header

/*
 * Copyright (c) 2011-2017 Your Organization (https://yourwebsite.com)
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public
 * License along with this program; if not, write to the
 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301 USA
 *
 * Authored by: Author <[email protected]>
*/

Reference:

elementary docs code reference

Clone this wiki locally