mifr/subsurface
1
0
Fork 0
mirror of https://github.com/subsurface/subsurface.git synced 2024-11-27 20:58:47 +00:00
Code Issues Projects Releases Packages Wiki Activity

CODINGSTYLE.md: use inline monospace formatting

Browse source 
Format keywords, classes, string examples, etc. in prose of
CODINGSTYLE.md using `inline formatting` with single backticks.

Signed-off-by: Andrei Rybak <rybak.a.v@gmail.com>
This commit is contained in:
Andrei Rybak 2023-03-26 18:24:54 +02:00 committed by bstoeger
parent 35f0a6af3b
commit 4946a112b3
1 changed files with 21 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

42
CODINGSTYLE.md
View file

@ -6,11 +6,11 @@ not yet fully consistent to these rules, but following these rules will make
sure that no one yells at you about your patches. sure that no one yells at you about your patches.
We have a script that can be used to reformat code to be reasonably close We have a script that can be used to reformat code to be reasonably close
to these rules; it's in scripts/whitespace.pl – this script requires to these rules; it's in `scripts/whitespace.pl` – this script requires
clang-format to be installed (which sadly isn't installed by default on clang-format to be installed (which sadly isn't installed by default on
any of our platforms; even on Mac where clang is the default compiler). any of our platforms; even on Mac where clang is the default compiler).
At the end of this file are some ideas for your .emacs file (if that's At the end of this file are some ideas for your `.emacs` file (if that's
your editor of choice) as well as for QtCreator. If you have settings for your editor of choice) as well as for QtCreator. If you have settings for
other editors that implement this coding style, please add them here. other editors that implement this coding style, please add them here.
@ -46,7 +46,7 @@ other editors that implement this coding style, please add them here.
} }
``` ```
* 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;
@ -125,7 +125,7 @@ other editors that implement this coding style, please add them here.
case. Where it seems appropriate, multiple, closely related classes can be case. Where it seems appropriate, multiple, closely related classes can be
in a single file with a more generic name. in a single file with a more generic name.
* 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) {
@ -185,20 +185,20 @@ other editors that implement this coding style, please add them here.
QLowEnergyService *service = qobject_cast<QLowEnergyService*>(sender()); QLowEnergyService *service = qobject_cast<QLowEnergyService*>(sender());
``` ```
- If the variable is a container that is only assigned to a local variable to - If the variable is a container that is only assigned to a local variable to
be able to use it in a range-based for loop be able to use it in a range-based `for` loop
``` ```
const auto serviceUuids = device.serviceUuids(); const auto serviceUuids = device.serviceUuids();
for (QBluetoothUuid id: serviceUuids) { for (QBluetoothUuid id: serviceUuids) {
``` ```
The variable has also to be const to avoid that Qt containers will do a The variable has also to be const to avoid that Qt containers will do a
deep copy when the range bases for loop will call the begin() method deep copy when the range bases `for` loop will call the `begin()` method
internally. internally.
* 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
``` ```
@ -209,10 +209,10 @@ other editors that implement this coding style, please add them here.
QString msgTitle = "Check for updates."; QString msgTitle = "Check for updates.";
``` ```
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_TR_FUNCTIONS` macro: the `tr()` functions by using the `Q_DECLARE_TR_FUNCTIONS` macro:
``` ```
#include <QCoreApplication> #include <QCoreApplication>
@ -222,23 +222,23 @@ other editors that implement this coding style, please add them here.
}; };
``` ```
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.
@ -254,10 +254,10 @@ other editors that implement this coding style, please add them here.
{ 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
@ -282,8 +282,8 @@ other editors that implement this coding style, please add them here.
* 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
@ -297,7 +297,7 @@ other editors that implement this coding style, please add them here.
### Emacs ### Emacs
These lines in your .emacs file should get you fairly close when it comes These lines in your `.emacs` file should get you fairly close when it comes
to indentation – many of the other rules you have to follow manually to indentation – many of the other rules you have to follow manually
``` ```
@ -393,7 +393,7 @@ style that you can select which should work well for our coding style.
### Vim ### Vim
As everybody knows vim is a way better editor than emacs and thus needs to be As everybody knows vim is a way better editor than emacs and thus needs to be
in this file too. Put this into your .vimrc and this should produce something in this file too. Put this into your `.vimrc` and this should produce something
close to our coding standards. close to our coding standards.
``` ```