Coding Style

General

This page defines the global coding style. For language specific coding styles, please have a look at:

Python
C
C++
Javascript
HTML: Use the w3school HTML5 syntax.
Lua: Use the Lua Style Guide.

#CS1 → #CS19 Programming languages

#CS1 Prefer Python to C

When creating new code, prefer Python to C programming language if performance is not an issue.

#CS2 Prefer C to C++

When creating new code, prefer C to C++ programming language, except if a C++ dependency is required (such as Qt) or if a complex object oriented design, including inheritance and other C++ features are strictly needed. C++ has a great complexity overhead over C that should be avoided as much as possible. Even with a C++ project, prefer a C public interface.

#CS3 Avoid programming languages other than Python, C and C++ for non web-programming

Unless you have a very good reason, avoid other programming languages. Obviously Lua is useful for template programming (such as what is implement in Webots PROTO nodes). This is motivated by the fact the all developers need to be familiar with a limited set of non-exotic languages.

#CS4 Avoid web server programming languages other than php / mysql

This is motivated by the fact the all developers need to be familiar with a limited set of non-exotic languages.

#CS20 → #CS39 Architecture design

#CS20 KISS: Keep it simple stupid

Unnecessary complexity should be avoided.

#CS21 Complex system design

Complex systems should be broken down into simpler systems. To design a complex system, one should go through the following steps, each step should be reviewed and approved before moving to the next step:

#CS21a: Produce a short overview text, including possibly diagrams, that describes the system addressing the following topics: context, input, output, features, performance, modular design, scalability.
#CS21b: Implement an architecture skeleton with placeholders for modules, review #CS21a.
#CS21c: Implement one module, review #CS21a and #CS21b. This step should be repeated (after review and approval) until all modules are implemented.

#CS22 Avoid dependencies

Dependencies are evil:

They often rely on source code that suddenly becomes not maintained anymore.
They are often overkill: we need only a few features of the dependency, all the rest is bloating us.
Web frameworks are painful to maintain, learn, and debug. Most of them can be avoided.

#CS40 → #CS59 Code quality

#CS40 No premature optimization

Don't complexify algorithms or data structure for optimization reasons. Optimization should take place at the very stage of development, only after the bottlenecks in a standard use case has been identified.

#CS41 Don't write unused code

Don't declare or implement unused variables or functions, under the pretext they could be used later. Implement them only when you need them.

#CS42 Don't pollute namespace

Use global static variables and static functions (C/C++) wherever needed to avoid polluting the global namespace.

#CS43 Choose names wisely for function and variable

The name of a function or variable should be sufficiently explicit to avoid a descriptive comment.

#CS44 No abbreviations

Don't use abbreviations. Exceptions are: n for "number of", init for "initialize", max for "maximum" and min for "minimum". C++ example:

computeAverage();  // NOT: compAvg();

#CS45 Acronyms should be written as other words (no capital letters)

C++ example:

exportHtmlSource(); // NOT: exportHTMLSource();

C example:

open_dvd_player(); // NOT: open_DVD_player();

#CS46 No useless comments

Don't comment unless strictly needed.

#CS47 Don't comment out code

Source code must not be commented out without an explanation. If commented out, the explanation must include one of the following keywords (allcaps) TODO: or FIXME:, so that we can easily find out and fix this later.

The only exception to this rule is commenting out debug statements, for example in C:

  // printf(stderr, "n_camera = %d\n", n_camera);

#CS48 Provide object description

An object definition (header file in C/C++ or source file in other languages for an object, interface, module, proto, etc.) should include a short comment describing what is the purpose of this object.

#CS49 Use simple header comments

In headers of files, comments do not include:

copyright (it is redundant with the general copyright of Webots)
author (it is maybe true for the first commit, but it becomes very quickly obsolete once someone changes the file)
modifications (it is difficult to maintain and it is redundant with the change log)
file name (it is redundant with the file name)
date (we don' care about it)

#CS50 Avoid double initialization

This is bad:

  int a = 0;
  if (c)
    a = 1;

And should be replace with:

  const int a = c ? 1 : 0;

The benefits are:

constness (makes the code easier to understand).
compactness (makes the code easier to read).
performance (minor in this case).

Sometimes constness cannot be achieved easily, however, double initialization should still be avoided, for example, this is bad:

  int a = 0;
  if (c) {
    a = 1;
    call_my_function();
  }

And should be replaced with:

  int a;
  if (!c)
    a = 0;
  else {
    a = 1;
    call_my_function();
  }

Which is arguably easier to understand and slightly more performant.

#CS51 avoid any else statement wherever a return, break or continue statement can be used instead