mirror of
https://github.com/subsurface/subsurface.git
synced 2025-02-19 22:16:15 +00:00
Update CodingStyle.md: placement of *, & and && declarators
Signed-off-by: Berthold Stoeger <bstoeger@mail.tuwien.ac.at>
This commit is contained in:
parent
c7f0e65b12
commit
d3dc698bba
1 changed files with 58 additions and 58 deletions
116
CodingStyle.md
116
CodingStyle.md
|
@ -20,18 +20,16 @@ other editors that implement this coding style, please add them here.
|
||||||
continuation lines that are aligned with tabs and then spaces
|
continuation lines that are aligned with tabs and then spaces
|
||||||
|
|
||||||
* all keywords followed by a '(' have a space in between
|
* all keywords followed by a '(' have a space in between
|
||||||
|
```
|
||||||
```
|
|
||||||
if (condition)
|
if (condition)
|
||||||
|
|
||||||
for (i = 0; i < 5; i++)
|
for (i = 0; i < 5; i++)
|
||||||
```
|
```
|
||||||
|
|
||||||
* function calls do NOT have a space between their name and argument
|
* function calls do NOT have a space between their name and argument
|
||||||
|
```
|
||||||
```
|
|
||||||
i = some_function(argument);
|
i = some_function(argument);
|
||||||
```
|
```
|
||||||
|
|
||||||
* usually there is no space on the inside of parenthesis (see examples
|
* usually there is no space on the inside of parenthesis (see examples
|
||||||
above)
|
above)
|
||||||
|
@ -41,17 +39,15 @@ other editors that implement this coding style, please add them here.
|
||||||
|
|
||||||
* all other opening curly braces follow at the end of the line, with a
|
* all other opening curly braces follow at the end of the line, with a
|
||||||
space separating them:
|
space separating them:
|
||||||
|
```
|
||||||
```
|
|
||||||
if (condition) {
|
if (condition) {
|
||||||
dosomething();
|
dosomething();
|
||||||
dosomethingelse();
|
dosomethingelse();
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
* both sides of an if / else clause either use or do not use curly braces:
|
* both sides of an if / else clause either use or do not use curly braces:
|
||||||
|
```
|
||||||
```
|
|
||||||
if (condition)
|
if (condition)
|
||||||
i = 4;
|
i = 4;
|
||||||
else
|
else
|
||||||
|
@ -63,55 +59,48 @@ other editors that implement this coding style, please add them here.
|
||||||
i = 4;
|
i = 4;
|
||||||
j = 6;
|
j = 6;
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
* use space to make visual separation easier
|
* use space to make visual separation easier
|
||||||
|
```
|
||||||
```
|
|
||||||
a = b + 3 + e / 4;
|
a = b + 3 + e / 4;
|
||||||
```
|
```
|
||||||
|
|
||||||
* continuation lines have the operator / comma at the end
|
* continuation lines have the operator / comma at the end
|
||||||
|
```
|
||||||
```
|
|
||||||
if (very_long_condition_1 ||
|
if (very_long_condition_1 ||
|
||||||
condition_2)
|
condition_2)
|
||||||
|
|
||||||
b = a + (c + d +
|
b = a + (c + d +
|
||||||
f + z);
|
f + z);
|
||||||
```
|
```
|
||||||
|
|
||||||
* in a C++ constructor initialization list, the colon is on the same line and
|
* in a C++ constructor initialization list, the colon is on the same line and
|
||||||
continuation lines are aligned as the rule above:
|
continuation lines are aligned as the rule above:
|
||||||
|
```
|
||||||
```
|
|
||||||
ClassName::ClassName() : x(1),
|
ClassName::ClassName() : x(1),
|
||||||
y(2),
|
y(2),
|
||||||
z(3)
|
z(3)
|
||||||
{
|
{
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
* unfortunate inconsistency
|
* unfortunate inconsistency
|
||||||
* C code usually uses underscores to structure names
|
- C code usually uses underscores to structure names
|
||||||
|
```
|
||||||
```
|
|
||||||
variable_in_C
|
variable_in_C
|
||||||
```
|
```
|
||||||
|
- In contrast, C++ code usually uses camelCase
|
||||||
* C++ code usually uses camelCase
|
```
|
||||||
|
|
||||||
```
|
|
||||||
variableInCPlusPlus
|
variableInCPlusPlus
|
||||||
```
|
```
|
||||||
|
|
||||||
where the two meet, use your best judgment and go for best consistency
|
where the two meet, use your best judgment and go for best consistency
|
||||||
(i.e., where does the variable "originate")
|
(i.e., where does the variable "originate")
|
||||||
|
|
||||||
* switch statements with blocks are a little bit special (to avoid indenting
|
* switch statements with blocks are a little bit special (to avoid indenting
|
||||||
too far)
|
too far)
|
||||||
|
```
|
||||||
```
|
|
||||||
switch (foo) {
|
switch (foo) {
|
||||||
case FIRST:
|
case FIRST:
|
||||||
whatever();
|
whatever();
|
||||||
|
@ -122,7 +111,7 @@ other editors that implement this coding style, please add them here.
|
||||||
do_something(i);
|
do_something(i);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Coding conventions
|
## Coding conventions
|
||||||
|
|
||||||
|
@ -130,7 +119,22 @@ other editors that implement this coding style, please add them here.
|
||||||
In C code we really like them to be at the beginning of a code block,
|
In C code we really like them to be at the beginning of a code block,
|
||||||
not interspersed in the middle.
|
not interspersed in the middle.
|
||||||
in C++ we are a bit less strict about this - but still, try not to go
|
in C++ we are a bit less strict about this - but still, try not to go
|
||||||
crazy.
|
crazy. Notably, in C++ the lifetime of a variable often coincides with the
|
||||||
|
lifetime of a resource (e.g. file) and therefore the variable is defined
|
||||||
|
at the place where the resource is needed.
|
||||||
|
|
||||||
|
* The `*`, `&` and `&&` declarators are grouped with the name, not the type
|
||||||
|
(classical C-style) as in `char *string` instead of `char* string`. This
|
||||||
|
reflects the precedence rules of the language: `int &i` means that the name
|
||||||
|
`i` stands for a reference [to an object with type `int`], not that
|
||||||
|
`i` stands for an object of the type [reference to `int`].
|
||||||
|
Although this may seem like hairsplitting (both interpretations
|
||||||
|
have the same effect) it is crucial in the
|
||||||
|
definition of multiple variables, such
|
||||||
|
as
|
||||||
|
```
|
||||||
|
struct dive *next, **pprev;
|
||||||
|
```
|
||||||
|
|
||||||
* In C++ code, we generally use explicit types in variable declarations for clarity.
|
* In C++ code, we generally use explicit types in variable declarations for clarity.
|
||||||
Use `auto` sparingly and only in cases where code readability improves.
|
Use `auto` sparingly and only in cases where code readability improves.
|
||||||
|
@ -150,71 +154,70 @@ other editors that implement this coding style, please add them here.
|
||||||
```
|
```
|
||||||
is easier to read than and conveys the same information as
|
is easier to read than and conveys the same information as
|
||||||
```
|
```
|
||||||
QLowEnergyService* service = qobject_cast<QLowEnergyService*>(sender());
|
QLowEnergyService *service = qobject_cast<QLowEnergyService*>(sender());
|
||||||
```
|
```
|
||||||
* text strings
|
* text strings
|
||||||
The default language of subsurface is US English so please use US English
|
The default language of subsurface is US English so please use US English
|
||||||
spelling and terminology.
|
spelling and terminology.
|
||||||
User-visible strings should be passed to the tr() function to enable
|
User-visible strings should be passed to the tr() function to enable
|
||||||
translation into other languages.
|
translation into other languages.
|
||||||
|
- like this
|
||||||
* like this
|
```
|
||||||
```
|
|
||||||
QString msgTitle = tr("Submit user survey.");
|
QString msgTitle = tr("Submit user survey.");
|
||||||
```
|
```
|
||||||
* rather than
|
- rather than
|
||||||
```
|
```
|
||||||
QString msgTitle = "Submit user survey.";
|
QString msgTitle = "Submit user survey.";
|
||||||
```
|
```
|
||||||
|
|
||||||
This works by default in classes (indirectly) derived from QObject. Each
|
This works by default in classes (indirectly) derived from QObject. Each
|
||||||
string to be translated is associated with a context, which corresponds
|
string to be translated is associated with a context, which corresponds
|
||||||
to the class name. Classes that are not derived from QObject can generate
|
to the class name. Classes that are not derived from QObject can generate
|
||||||
the tr() functions by using the Q_DECLARE_FUNCTIONS macro:
|
the tr() functions by using the `Q_DECLARE_FUNCTIONS` macro:
|
||||||
```
|
```
|
||||||
#include <QCoreApplication>
|
#include <QCoreApplication>
|
||||||
|
|
||||||
class myClass {
|
class myClass {
|
||||||
Q_DECLARE_TR_FUNCTIONS(gettextfromC)
|
Q_DECLARE_TR_FUNCTIONS(gettextfromC)
|
||||||
...
|
...
|
||||||
};
|
};
|
||||||
```
|
```
|
||||||
|
|
||||||
As an alternative, which also works outside of class context, the tr()
|
As an alternative, which also works outside of class context, the tr()
|
||||||
function of a different class can be called. This avoids creating multiple
|
function of a different class can be called. This avoids creating multiple
|
||||||
translations for the same string:
|
translations for the same string:
|
||||||
```
|
```
|
||||||
gettextFromC::tr("%1km")
|
gettextFromC::tr("%1km")
|
||||||
```
|
```
|
||||||
|
|
||||||
The gettextFromC class in the above example was created as a catch-all
|
The gettextFromC class in the above example was created as a catch-all
|
||||||
context for translations accessed in C code. But it can also be used
|
context for translations accessed in C code. But it can also be used
|
||||||
from C++ helper functions. To use it from C, include the "core/gettext.h"
|
from C++ helper functions. To use it from C, include the "core/gettext.h"
|
||||||
header and invoke the translate() macro:
|
header and invoke the translate() macro:
|
||||||
```
|
```
|
||||||
#include "core/gettext.h"
|
#include "core/gettext.h"
|
||||||
|
|
||||||
report_error(translate("gettextFromC", "Remote storage and local data diverged"));
|
report_error(translate("gettextFromC", "Remote storage and local data diverged"));
|
||||||
```
|
```
|
||||||
It is crucial to pass "gettextFromC" as a first macro argument so that Qt
|
It is crucial to pass "gettextFromC" as a first macro argument so that Qt
|
||||||
is able to associate the string with the correct context.
|
is able to associate the string with the correct context.
|
||||||
The translate macro returns a cached C-style string, which is generated at runtime
|
The translate macro returns a cached C-style string, which is generated at runtime
|
||||||
when the particular translation string is encountered for the first time.
|
when the particular translation string is encountered for the first time.
|
||||||
It remains valid during the whole application's life time.
|
It remains valid during the whole application's life time.
|
||||||
|
|
||||||
Outside of function context, the QT_TRANSLATE_NOOP macro can be used as in
|
Outside of function context, the `QT_TRANSLATE_NOOP` macro can be used as in
|
||||||
```
|
```
|
||||||
struct ws_info_t ws_info[100] = {
|
struct ws_info_t ws_info[100] = {
|
||||||
{ QT_TRANSLATE_NOOP("gettextFromC", "integrated"), 0 },
|
{ QT_TRANSLATE_NOOP("gettextFromC", "integrated"), 0 },
|
||||||
{ QT_TRANSLATE_NOOP("gettextFromC", "belt"), 0 },
|
{ QT_TRANSLATE_NOOP("gettextFromC", "belt"), 0 },
|
||||||
{ QT_TRANSLATE_NOOP("gettextFromC", "ankle"), 0 },
|
{ QT_TRANSLATE_NOOP("gettextFromC", "ankle"), 0 },
|
||||||
{ QT_TRANSLATE_NOOP("gettextFromC", "backplate"), 0 },
|
{ QT_TRANSLATE_NOOP("gettextFromC", "backplate"), 0 },
|
||||||
{ QT_TRANSLATE_NOOP("gettextFromC", "clip-on"), 0 },
|
{ QT_TRANSLATE_NOOP("gettextFromC", "clip-on"), 0 },
|
||||||
};
|
};
|
||||||
```
|
```
|
||||||
Note that here, the texts will be scheduled for translation with the "gettextFromC"
|
Note that here, the texts will be scheduled for translation with the "gettextFromC"
|
||||||
context, but the array is only initialized with the original text. The actual
|
context, but the array is only initialized with the original text. The actual
|
||||||
translation has to be performed later in code. For C-code, the QT_TRANSLATE_NOOP
|
translation has to be performed later in code. For C-code, the `QT_TRANSLATE_NOOP`
|
||||||
macro is defined in the "core/gettext.h" header.
|
macro is defined in the "core/gettext.h" header.
|
||||||
|
|
||||||
* UI text style
|
* UI text style
|
||||||
|
@ -236,11 +239,9 @@ struct ws_info_t ws_info[100] = {
|
||||||
|
|
||||||
|
|
||||||
* string manipulation
|
* string manipulation
|
||||||
|
|
||||||
* user interface
|
* user interface
|
||||||
In UI part of the code use of QString methods is preferred, see this pretty
|
In UI part of the code use of QString methods is preferred, see this pretty
|
||||||
good guide in [QString documentation][1]
|
good guide in [QString documentation][1]
|
||||||
|
|
||||||
* core components
|
* core components
|
||||||
In the core part of the code, C-string should be used.
|
In the core part of the code, C-string should be used.
|
||||||
C-string manipulation is not always straightforward specifically when
|
C-string manipulation is not always straightforward specifically when
|
||||||
|
@ -248,7 +249,6 @@ struct ws_info_t ws_info[100] = {
|
||||||
to help with this. Documentation and usage examples can be found in
|
to help with this. Documentation and usage examples can be found in
|
||||||
[core/membuffer.h][2]
|
[core/membuffer.h][2]
|
||||||
|
|
||||||
|
|
||||||
## Sample Settings
|
## Sample Settings
|
||||||
|
|
||||||
### Emacs
|
### Emacs
|
||||||
|
|
Loading…
Add table
Reference in a new issue