1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
# MuJoCo Style Guide
The MuJoCo codebase follows an internally consistent style that values
compactness and readability. Please try to follow the style guide as closely as
possible in your code contributions.
### Scope of this guide
MuJoCo has three main code categories:
1. **C code:** MuJoCo's core codebase. It consists of public headers under
`include/` and C source files and internal headers under `src/`. This style
guide primarily concerns itself with this category.
2. **Legacy C++:** Files under `src/user/` and `src/xml/`. These do not
necessarily follow best C++ practices. We intend to gradually replace these with
new code that follows the [Google C++
style](https://google.github.io/styleguide/cppguide.html) over time.
3. **New code:** This includes C++ files under `test/` and `python/` and C#
files under `unity/`. Added by DeepMind engineers, this code adheres to the
[Google style](https://google.github.io/styleguide/).
### General principles
Where any aspect of coding style is not explicitly spelled out in this guide,
the following principle is followed:
| Maximise consistency with the rest of the code. |
| --- |
If there is a contradiction between this guide and existing code, the guide
takes precedence. Additional principles include:
- Follow the [naming conventions](https://mujoco.readthedocs.io/en/latest/programming.html#naming-convention).
- Be sparing with horizontal space: Try to keep lines short, avoid line-breaks
where possble.
- Be generous with vertical space: Empty lines between code blocks are good.
- Keep names short.
- Inline comments are part of the code, treat them as such.
- Use American English in comments and documentation.
### Specific rules for C code
Over time, this style guide will be expanded to cover most aspects of C
programming in the MuJoCo codebase. In the meantime, it is usually enough to
inspect existing code and try to follow its example.
If there are any consistent coding patterns that are specific to the MuJoCo
codebase but aren't mentioned in the guide, the guide should be expanded. If you
spot such a pattern, feel free to send a PR to update the guide.
#### Indentation
2-space indents, using space characters rather than tabs.
#### Line length
Line length is 100 characters. In rare situations, like the collision table at
the top of
[engine_collision_driver.c](https://github.com/deepmind/mujoco/blob/c8ff7b3d341560e8cc33fbdcaffbcdbc4c32327c/src/engine/engine_collision_driver.c#L36),
longer lines are alowed for readability.
#### Comments
MuJoCo makes generous use of short, one-line comments describing the code block
just below them. They are considered an essential part of the code. Comments
should be:
- As succinct as possible, while maintaining clarity.
- Preceded by an empty line, unless at the top of a block.
- Uncapitalized and not terminated by a full-stop.
A helpful heuristic regarding in-code comments is that the reader should be able
to get a sense of what is happening in a function just by reading the comments.
An exception to the third bullet point above are function declaration comments
in public header files which are considered to be docstrings rather than code
and are therefore capitalized and terminated by a full stop. These docstrings
are required.
#### Braces
- MuJoCo uses
[attached K&R braces](https://en.wikipedia.org/wiki/Indentation_style#Variant:_mandatory_braces),
including for one-line blocks:
```C
// transpose matrix
void mju_transpose(mjtNum* res, const mjtNum* mat, int nr, int nc) {
for (int i=0; i<nr; i++) {
for (int j=0; j<nc; j++) {
res[j*nr+i] = mat[i*nc+j];
}
}
}
```
- Brace-less single line statements are allowed outside of `engine/` code, for
similar, repeated blocks, that do not contain flow control statements (`return`,
`continue`, etc.). For an example of this exception, inspect the [`mjCModel`
destructor](https://github.com/deepmind/mujoco/search?q=repo%3Adeepmind%2Fmujoco+filename%3Auser_model.cc).
- Unattached braces are allowed in `if/else` blocks, when inserting a comment
before the `else`:
```C
// rotate vector by quaternion
void mju_rotVecQuat(mjtNum res[3], const mjtNum vec[3], const mjtNum quat[4]) {
// null quat: copy vec
if (quat[0]==1 && quat[1]==0 && quat[2]==0 && quat[3]==0) {
mju_copy3(res, vec);
}
// regular processing
else {
mjtNum mat[9];
mju_quat2Mat(mat, quat);
mju_rotVecMat(res, vec, mat);
}
}
```
#### Spacing
- MuJoCo encourages judicious use of spacing around operators to promote
readability. For example below, note the lack of spaces around the
multiplication operator, and the aligning spaces in the second and fourth
assignments:
```C
// time-derivative of quaternion, given 3D rotational velocity
void mju_derivQuat(mjtNum res[4], const mjtNum quat[4], const mjtNum vel[3]) {
res[0] = 0.5*(-vel[0]*quat[1] - vel[1]*quat[2] - vel[2]*quat[3]);
res[1] = 0.5*( vel[0]*quat[0] + vel[1]*quat[3] - vel[2]*quat[2]);
res[2] = 0.5*(-vel[0]*quat[3] + vel[1]*quat[0] + vel[2]*quat[1]);
res[3] = 0.5*( vel[0]*quat[2] - vel[1]*quat[1] + vel[2]*quat[0]);
}
```
- Spaces are not allowed around comparison operators in `for` statements and
inside array subscripts `[]`. For an example, inspect the `mju_transpose`
implementation above.
- Three empty lines between function declarations.
#### Variable declarations
Historically the MuJoCo C codebase used exclusively C89-style variable
declarations, with all stack variables pre-declared at the top of the function.
We are in the process of migrating the code to the C99 convention of declaring
variables at the narrowest possible scope. For example iterator variables in
for-loops are mostly declared in the narrow scope, as in the `mju_transpose`
example above.
New code should use the C99 convention. When editing an existing function,
please move existing variable declarations into local scope. Pull requests
helping us to complete the migration are very welcome.
|
