-
-
Notifications
You must be signed in to change notification settings - Fork 1.7k
Coding Style
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.
When creating new code, prefer Python to C programming language if performance is not an issue.
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.
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.
This is motivated by the fact the all developers need to be familiar with a limited set of non-exotic languages.
Unnecessary complexity should be avoided.
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.
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.
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.
Don't declare or implement unused variables or functions, under the pretext they could be used later. Implement them only when you need them.
Use global static variables and static functions (C/C++) wherever needed to avoid polluting the global namespace.
The name of a function or variable should be sufficiently explicit to avoid a descriptive comment.
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();
C++ example:
exportHtmlSource(); // NOT: exportHTMLSource();
C example:
open_dvd_player(); // NOT: open_DVD_player();
Don't comment unless strictly needed.
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);
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.
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)
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.
This is bad:
int my_func() {
int c;
if (a == 0)
c = 1;
else {
my_other_function();
c = 2;
}
return c;
}
And should be replaced with:
int my_func() {
if (a == 0)
return 1;
my_other_function();
return 2;
}
Which is more readable and more compact.